Discovery Start: Initialize Codebase Discovery

Purpose

Initialize codebase discovery by detecting project type, identifying key directories, and creating a context file that subsequent discovery skills will use. This is the first step in building a component catalog.

Mastery Levels (ShuHaRi)

Shu (守): Follow all steps, detect all languages, create complete context file.

Ha (破): Focus on primary language only for targeted discovery.

Ri (離): Integrate with project-specific conventions or monorepo structures.

Context

When to use:

• •Starting discovery on a new codebase
• •After significant structural changes to the project
• •When component catalog needs refresh

When to skip:

• •work/discovery/context.yaml already exists and is current
• •Quick re-scan of specific directory (use /rai-discover-scan directly with path)

Inputs required:

• •Access to project root directory
• •Ability to list files and detect extensions

Output:

• •work/discovery/context.yaml — Project context for discovery
• •Ready for /rai-discover-scan

Steps

Step 1: Detect Languages Present

Scan the project for source files and identify languages.

Run these counts in parallel (all independent):

# Count files by extension (run in parallel)
find . -type f -name "*.py" | wc -l    # Python
find . -type f -name "*.ts" | wc -l    # TypeScript
find . -type f -name "*.js" | wc -l    # JavaScript
find . -type f -name "*.tsx" | wc -l   # React TSX
find . -type f -name "*.jsx" | wc -l   # React JSX

Supported languages:

• •python — .py files
• •typescript — .ts, .tsx files
• •javascript — .js, .jsx files

Record: List of detected languages with file counts.

Verification: At least one supported language detected.

If you can't continue: No supported languages → Discovery not applicable to this codebase.

Step 2: Identify Root Directories

Find the main source directories:

Common patterns:

• •src/ — Standard source directory
• •lib/ — Library code
• •app/ — Application code (Next.js, Rails, etc.)
• •packages/ — Monorepo packages

ls -d src/ lib/ app/ packages/ 2>/dev/null || echo "Check project structure"

Record: List of root directories to scan.

Verification: At least one scannable directory identified.

If you can't continue: No clear source directory → Ask user to specify.

Step 3: Identify Entry Points

Find main entry points for context:

Python:

• •src/*/cli/main.py — CLI entry
• •src/*/__main__.py — Module entry
• •main.py — Root entry

TypeScript/JavaScript:

• •src/index.ts — Library entry
• •src/main.ts — App entry
• •package.json main field

Record: Entry point paths (informational, helps Rai understand structure).

Verification: Entry points identified (optional, proceed if not found).

Step 4: Create Context File

Create work/discovery/context.yaml with detected information:

# work/discovery/context.yaml
# Generated by /rai-discover-start
# Do not edit manually — regenerate with /rai-discover-start

project:
  name: {project_name}  # From directory name or package.json/pyproject.toml
  languages:
    - python           # List detected languages
  root_dirs:
    - src/rai_cli    # Directories to scan
  entry_points:
    - src/rai_cli/cli/main.py  # Main entry points
  detected_at: {ISO_TIMESTAMP}

status: initialized

Write the file using the Write tool.

Verification: File created at work/discovery/context.yaml.

If you can't continue: Write permission error → Check directory permissions.

Step 5: Display Summary

Present the discovery context to the user:

## Discovery Initialized

**Project:** {name}
**Languages:** {list}
**Directories:** {list}
**Entry Points:** {list}

**Context file:** `work/discovery/context.yaml`

### Next Step

Run `/rai-discover-scan` to extract symbols and synthesize descriptions.

Or specify a subdirectory for targeted scan:
> /rai-discover-scan src/specific/module

Verification: Summary displayed; user knows next step.

Output

• •Artifact: work/discovery/context.yaml
• •Telemetry: skill_event via Stop hook
• •Next: /rai-discover-scan

Discovery Context Schema

project:
  name: string           # Project name
  languages: string[]    # Detected languages
  root_dirs: string[]    # Directories to scan
  entry_points: string[] # Main entry points (informational)
  detected_at: string    # ISO timestamp

status: string           # initialized | scanning | validated | complete

Notes

Project Name Detection

Priority order:

1. •pyproject.toml → [project].name
2. •package.json → name
3. •Directory name (fallback)

Monorepo Support

For monorepos with packages/:

• •List each package as separate root_dir
• •Or focus on specific package if user specifies

Re-initialization

Running /rai-discover-start again will overwrite context.yaml. This is intentional — use when project structure changes significantly.

References

• •Next skill: /rai-discover-scan
• •Design: work/stories/f13.3/design.md
• •Epic: E13 Discovery