/code-analysis-flow

name: code-analysis-flow
description: "Workflow for reverse-engineering a codebase into grounded architecture docs, requirements capture, etc."
tags: ["workflow"]
baseSchema: docs/schemas/workflow.md

<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>

<prerequisites phase="0" applies="ALL">

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).

</prerequisites>

<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">

1. Precondition: user explicitly requested requirements reverse-engineering (e.g., "extract requirements", "generate SRS", "generate specifications", "from existing code", "produce EARS/NFRs from code"). If absent, skip this phase entirely. 2. Use `reverse-engineering` skill to distill intent, then `requirements-authoring` skill to produce atomic, testable functional and non-functional requirements with SMART, MECE, acceptance criteria, EARS phrasing, priority (MoSCoW), and predecessors. 3. Input: scope + context. Output: `docs/REQUIREMENTS/` per `requirements-authoring` layout, with HITL per-unit approval owned by that skill. 4. Required skills: `reverse-engineering`, `requirements-authoring` 5. Update `code-analysis-flow-state.md`. 6. Partition workspace USING SKILL `large-workspace-handling` (Summarization & Indexing strategy): every file belongs to exactly one scope; subagents analyze per-module in parallel. 7. Ensure it is possible to rewrite using requirements only completely from scratch without old code present.

</requirements_branch>

<analyze_small phase="5" applies="SMALL" subagent="architect" role="Senior systems analyst producing a single grounded analysis document" subagent_required_model="Claude Opus 5, GPT-5.6 Sol, Gemini 3.7 Flash">

1. Produce one grounded analysis document covering: components, data models, patterns, logic flow as conceptual algorithm (no line-by-line), boundary and edge cases, unhandled edges, sequence and dependency diagrams in Mermaid, external dependencies with purpose. 2. Reference specific files and line ranges; keep co