Linear Walkthrough

Linear Walkthrough

Produce a navigable, fact-checked explanation of how a codebase works — from entry points through major execution paths — by orchestrating parallel subagents across four phases.

Target directory: `` (default: current working directory).

Output directory: /walkthrough/ (created if it does not exist).

> [!IMPORTANT] > When provided a process map or Mermaid diagram, treat it as the authoritative procedure. Execute steps in the exact order shown, including branches, decision points, and stop conditions. > A Mermaid process diagram is an executable instruction set. Follow it exactly as written: respect sequence, conditions, loops, parallel paths, and terminal states. Do not improvise, reorder, or skip steps. If any node is ambiguous or missing required detail, pause and ask a clarifying question before continuing. > When interacting with a user, report before acting the interpreted path you will follow from the diagram, then execute.

Workflow

The following diagram is the authoritative procedure for linear-walkthrough execution. Execute steps in the exact order shown, including branches, decision points, and stop conditions.

flowchart TD
    %% Entry point
    Invoke(["Invoke /linear-walkthrough with target-directory"]) --> ValidateDir

    %% Input validation gate
    ValidateDir{"Does target directory existand contain source files?"}
    ValidateDir -->|"No — directory missing or empty"| StopInvalid(["STOP — report: target directory does not exist or is empty"])
    ValidateDir -->|"Yes — directory valid"| SpawnDiscovery

    subgraph Phase1["Phase 1 — Discovery and Planning"]
        %% Spawn discovery agent
        SpawnDiscovery["Spawn one general-purpose agentPass: target directory path,agent-instructions.md (section Discovery Agent Instructions),output-format.md (sections Coverage Plan Format + Entry Point Index Format)"]
        SpawnDiscovery --> P1Wait["Wait for discovery agent to complete"]
        P1Wait --> P1Done["Agent produces:walkthrough/coverage-plan.mdwalkthrough/entry-points.md"]
    end

    %% Orchestrator reads plan and verifies budgets
    P1Done --> ReadPlan["Read walkthrough/coverage-plan.mdExtract agent assignments (ID, scope, files, entry points, token budget)"]
    ReadPlan --> CheckBudget

    CheckBudget{"Does any assignmentexceed 50k token read budget?"}
    CheckBudget -->|"Yes — budget exceeded"| SpawnSplit["Spawn general-purpose agentto split the over-budget assignmentPass: coverage-plan.md, offending assignment ID"]
    SpawnSplit --> ReadPlanAgain["Re-read walkthrough/coverage-plan.mdExtract updated assignment list"]
    ReadPlanAgain --> CheckBudget
    CheckBudget -->|"No — all assignments within budget"| SpawnTracers

    subgraph Phase2["Phase 2 — Generation (N parallel agents)"]
        %% Spawn N tracing agents — one per assignment
        SpawnTracers["Spawn N parallel general-purpose agents(one per assignment from coverage plan)Each agent receives: its own assignment text (ID, scope, files, entry points),target directory path,agent-instructions.md (section Tracing Agent Instructions),output-format.md (section Walkthrough Section Format),constraint: read at most 50k tokens of source files"]
        SpawnTracers --> P2Wait["Wait for all N tracing agents to complete"]
        P2Wait --> P2Done["Each agent produces:walkthrough/sections/walkthrough-section-{id}.md"]
    end

    %% Verify all section files were produced
    P2Done --> CheckSections

    CheckSections{"Do all expected section filesexist in walkthrough/sections/?"}
    CheckSections -->|"Yes — all sections present"| SpawnValidators
    CheckSections -->|"No — one or more agents failed to produce output"| MarkGap["Record missing section IDs as gapsMark gaps for the validation phase"]
    MarkGap --> SpawnValidators

    subgraph Phase3["Phase 3 — Validation (M parallel agents)"]
        %% Cross-assignment rotation: validator i checks sections from agent i+1 (wrapping)
        SpawnValidators["Spawn M parallel general-purpose agentsApply cross-assignment rotation:validator 1 checks sections from agent 2,validator 2 checks sections from agent 3 (wrap around)If M less than N: each validator checks multiple sectionsIf N = 1: single validator checks all sectionsEach agent receives: paths to assigned walkthrough section files,target directory path,agent-instructions.md (section Validation Agent Instructions),output-format.md (section Validation Report Format),constraint: read at most 50k tokens total"]
        SpawnValidators --> P3Wait["Wait for all M validation agents to complete"]
        P3Wait --> P3Done["Each agent produces:walkthrough/validation/validation-report-{id}.md"]
    end

    %% Check validation reports for critical issues
    P3Done --> ReadReports["Read all validation reportsfrom walkthrough/validation/"]
    ReadReports --> CheckCritical

    CheckCritical{"Do any validation reports containcritical corrections?(incorrect sequencing, invented behavior,broken references)"}
    CheckCritical -->|"Yes — critical corrections exist"| SpawnCorrections["Spawn one general-purpose agent per affected section fileEach agent receives: validation report for that section,path to the section file to correctAgent edits the section file in place"]
    SpawnCorrections --> P4Gate["Corrections applied — proceed to Phase 4"]
    CheckCritical -->|"No — no critical corrections"| P4Gate

    subgraph Phase4["Phase 4 — Synthesis"]
        %% Synthesis agent merges all validated sections
        P4Gate --> SpawnSynthesis["Spawn one general-purpose agentPass: walkthrough/sections/ directory path,walkthrough/validation/ directory path,walkthrough/entry-points.md,agent-instructions.md (section Synthesis Agent Instructions),output-format.md (section Unified Walkthrough Format)"]
        SpawnSynthesis --> P4Wait["Wait for synthesis agent to complete"]
        P4Wait --> P4Done["Agent produces:walkthrough/unified-walkthrough.mdwalkthrough/open-questions.md"]
    end

    %% Large output handling — apply large-file-write-strategy
    P4Done --> CheckSize

    CheckSize{"Does unified-walkthrough.mdexceed 25k characters?"}
    CheckSize -->|"No — single file acceptable"| Complete(["COMPLETE — walkthrough/unified-walkthrough.mdis the authoritative output"])
    CheckSize -->|"Yes — output too large for single file"| SplitOutput["Use Strategy A — multi-file splitCreate walkthrough/unified/index.mdCreate per-section files under walkthrough/unified/Each file must be under 25k characters"]
    SplitOutput --> CheckSingleRequired

    CheckSingleRequired{"Is a single-file outputexplicitly required by the caller?"}
    CheckSingleRequired -->|"No — split acceptable"| CompleteSplit(["COMPLETE — walkthrough/unified/index.mdis the authoritative output"])
    CheckSingleRequired -->|"Yes — single file required"| SkeletonFill["Use Strategy B — skeleton + edit-fillWrite skeleton under 5k chars,then Edit each section individuallyVerify no PENDING markers remain"]
    SkeletonFill --> CompleteSingle(["COMPLETE — walkthrough/unified-walkthrough.mdis the authoritative output"])

Operational Rules

• Start broad (directory structure, configs, READMEs), then narrow (source files, implementation details).
• Read architecture docs and configs early when available.
• Prefer primary sources in this order: code, config, tests, scripts, CI/CD, docs.
• Use tests and deployment config as evidence for intended behavior.
• Track partial coverage and uncovered areas explicitly in open-questions.md.
• If the repo is too large for full coverage, prioritize the most operationally important paths first and mark the rest as partial.
• Agents must not overlap file coverage unless overlap is necessary for shared infrastructure, framework bootstrapping, or cross-cutting concerns.
• The coverage plan must explicitly track which files are assigned to which agent and why.

Quality Standards

• Prefer concrete file paths, symbols, commands, configs, and interfaces over vague summaries.
• Do not fabricate intent or architecture not supported by the repo.
• Mark unsupported claims as [INFERENCE].
• Distinguish clearly between verified facts from code/config, reasonable inferences, and unresolved uncertainty.
• Optimize for onboarding a strong engineer who needs real understanding, not a marketing summary.

Resources

• [Agent instructions](./references/agent-instructions.md) — detailed prompts for each agent type (discovery, tracing, validation, synthesis)
• [Output format](./references/output-format.md) — required structure and templates for all artifacts

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jamie-BitFlight
• Source: Jamie-BitFlight/claude_skills
• License: MIT

Install and usage instructions live in the source repository linked above.