stefancgillberg Discover
Purpose
Run the full discovery pipeline in one pass: detect languages, extract and describe components, generate architecture docs, and build the knowledge graph.
Mastery Levels (ShuHaRi)
- Shu: Show each phase, explain results, pause after describe + document
- Ha: Auto-run detect + extract, pause at describe, auto-document if <10 modules
- Ri: Full pipeline with inline approve, minimal pauses
Context
When to use: After rai init --detect on an existing codebase, or when architecture changes significantly.
When to skip: Graph is current and no structural changes since last discovery.
Inputs: Project root with source code. Optionally specify language to limit scan.
| Condition | Action |
|---|---|
rai init --detect done |
Continue |
No .raise/manifest.yaml |
Stop: run rai init --detect first |
| Only updating docs | Use /rai-docs-update instead |
Steps
Step 1: Detect (auto)
rai discover scan . --output summary
From summary, extract languages, source directories, entry points. Write work/discovery/context.yaml with project name (from pyproject.toml → package.json → directory), languages, root_dirs, entry_points, detected_at.
Step 2: Extract (auto)
For each detected language and root directory:
rai discover scan {root_dir} --language {language} --output json | rai discover analyze --output human
Produces work/discovery/analysis.json with confidence scores, auto-categorization, and module grouping.
Step 3: Describe (HITL)
Handle components by confidence tier:
| Confidence | Action |
|---|---|
| High (≥70) | Accept auto_purpose and auto_category silently — no human review |
| Medium (40-69) | Present by module batch with LLM-suggested descriptions |
| Low (<40) | Scale gate first, then review |
Medium flow: Present table per module (name, kind, category, suggested purpose, score). Ask: "Approve batch? [Approve all / Edit specific]"
Low scale gate (all low AND >50): Offer modes: A) by layer/namespace, B) user nominates key components + bulk-skip, C) auto-accept by naming pattern (*Handler, *Repository). Otherwise review individually.
Write components-draft.yaml and export to components-validated.json (graph node format).
Step 4: Document (HITL)
Module docs: For each module, write governance/architecture/modules/{name}.md with YAML frontmatter (type, name, purpose, status, depends_on, depended_by, components) and body (Purpose, Architecture, Key Files, Dependencies, Conventions). Detect modules by language: Python (__init__.py), C# (.csproj + namespaces), PHP (composer.json PSR-4).
System docs: Generate 4 docs from governance + discovery data:
system-context.md— what, who, why, external systems (fromvision.md)system-design.md— layers, data flows, constraints (fromguardrails.md+ module deps)domain-model.md— bounded contexts, context map (from module deps + components)index.md— compact overview <2K tokens (system overview, module map, key constraints)
Present for review.
Step 5: Build (auto)
rai graph build
rai graph query "module dependencies"
Verify module nodes in graph, no stale references. Present summary: project, components by tier, modules, graph node/edge counts.
Output
| Item | Destination |
|---|---|
| Context file | work/discovery/context.yaml |
| Component catalog | work/discovery/components-validated.json |
| Module docs | governance/architecture/modules/*.md |
| System docs | governance/architecture/*.md |
| Knowledge graph | .raise/rai/memory/index.json |
| Next | /rai-session-start or /rai-project-onboard |
Quality Checklist
- All supported languages detected (not just primary)
- High-confidence components auto-accepted (no unnecessary HITL)
- Medium-confidence presented by module batch (not per-component)
- Scale gate applied for all-low large codebases (>50 components)
- Module frontmatter includes all required fields
- Module prose explains WHY, not just WHAT (new contributor test)
- Index under 2K tokens for session-loadable context
- Graph built and verified as final step
- NEVER include generated/build directories in root_dirs
- NEVER generate placeholder docs for modules with no real code
References
- CLI:
rai discover scan --help,rai discover analyze --help - Graph:
rai graph build,rai graph query - Categories: service, model, utility, handler, parser, builder, schema, command, test
- Confidence tiers: high ≥70, medium 40-69, low <40
- Replaces:
/rai-discover-start,/rai-discover-scan,/rai-discover-validate,/rai-discover-document