code-analysis-flow

<code_analysis_flow>

<description_and_purpose>

Problem: Code analysis degrades into transcription, drifts into suggestions/refactors, or stalls when codebase exceeds single-agent context; assumptions and unknowns are silently adopted. Solution: Thin, sequential workflow that classifies SMALL vs LARGE codebase, delegates analysis to the reverse-engineering skill, must partition LARGE codebases via large-workspace-handling, gates critical/high unknowns through questioning, and optionally extracts requirements via requirements-authoring. Grounded by links, HITL at unknowns and final review. Validation: Output files exist under docs/<feature>/; every claim traces to code/docs; no generated or suggested implementation; open questions and assumptions are documented; state file reflects phase evidence.

</description_and_purpose>

<workflow_phases>

1. All Rosetta prep steps MUST be FULLY completed
2. USE SKILL load-project-context, orchestration, hitl
3. MUST ALWAYS use todo tasks ledger, ASAP. Phases are sequential. Independent tasks can run in parallel. Module analysis in LARGE codebases runs in parallel via SKILL large-workspace-handling.
4. No rush, take your time, MUST FOLLOW WORKFLOW ENTIRELY, no skipping
5. Orchestrator trusts skills to own execution internals; coordinates sequence, artifacts, state, and approvals only.
6. State file: agents/TEMP/<FEATURE>/code-analysis-flow-state.md updated after each phase.
7. Documentation principle: ground with links; no code generation, no suggestions, no speculation. See best_practices for sizing and diagram rules.
8. If /goal is set repeat phases 4-8 until goal is met.
9. If task is to extract/document/reverse engineer requirements or specifications from existing app/code:
   • This is much more intense per subagent: reclassify SMALL if < 10 source files, otherwise LARGE and MUST USE large-workspace-handling.
   • Both orchestrator and subagents MUST USE SKILL requirements-authoring
   • Spawn MULTIPLE subagents with each handling one unit of analysis (one module, one community, one screen, one controller, one endpoint, etc) to effectively prevent hallucinations by narrowing scope down for phases requirements_branch and review (more agents - less scope each).

<context_load phase="1" applies="ALL" subagent="discoverer" role="Context gatherer for analysis scope" subagent_required_model="Claude Sonnet 5, GPT-5.6 Terra, Gemini 3.7 Flash">

1. Read all lines of docs/CONTEXT.md, docs/ARCHITECTURE.md, agents/IMPLEMENTATION.md; grep headers of docs/CODEMAP.md, docs/TECHSTACK.md, docs/DEPENDENCIES.md if present.
2. Input: user analysis request. Output: loaded project context + entry points (APIs, webhooks, CLIs, cron jobs).
3. Recommended skills: load-project-context
4. Update code-analysis-flow-state.md.

</context_load>

<scope_and_classify phase="2" applies="ALL" subagent="discoverer" role="Scope and size scanner" subagent_required_model="Claude Sonnet 5, GPT-5.6 Terra, Gemini 3.7 Flash">

1. Classify target codebase: LARGE if 100+ files recursively or 4+ modules; otherwise SMALL.
2. Identify target scope (repo, module, feature, path glob). Record boundaries and non-goals.
3. Input: user request + loaded context. Output: scope (paths), size (SMALL|LARGE), module-list (LARGE only).
4. Required skills: reasoning
5. Update code-analysis-flow-state.md.

</scope_and_classify>

<clarify_unknowns phase="3" applies="ALL" type="HITL">

1. Surface only critical/high assumptions and unknowns affecting analysis accuracy; skip low and nit-picking.
2. Ask up to 10 targeted, MECE, one-decision-per-question batch. Include safe default per question.
3. Record resolved answers and unresolved items as assumptions; both are persisted in final output.
4. Required skills: questioning
5. Update code-analysis-flow-state.md.

</clarify_unknowns>

<requirements_branch phase="4" applies="ALL" when="user requested requirements reverse-engineering" subagent="architect" role="Requirements engineer extracting intent from code" subagent_required_model="Claude Opus 5, GPT-5.6 Sol, Gemini 3.7 Flash">