Agent skill
unwinding-codebase
Use after unwind:start to orchestrate layer-by-layer analysis using specialist subagents
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/unwinding-codebase
SKILL.md
Unwinding Codebase
Requires: docs/unwind/architecture.md
Produces: docs/unwind/layers/*/ folders via subagents (each with index.md + section files)
Principles: See analysis-principles.md - completeness, machine-readable, link to source, no commentary, incremental writes.
Process
Step 1: Parse Architecture Document
- Read
docs/unwind/architecture.md - Extract
repository.link_formatfor source linking - Extract YAML
layersblock - Build dependency graph
- Skip layers with
status: not_detected
Step 2: Execution Phases
Phase 1: database (no dependencies)
Phase 2: domain_model (needs database)
Phase 3: service_layer (needs domain_model)
Phase 4: api, messaging (parallel - need service_layer)
Phase 5: frontend (optional - needs api)
Phase 6: unit_tests, integration_tests, e2e_tests (parallel - no layer dependencies)
Step 3: Dispatch Subagents
For each layer, dispatch:
Task(subagent_type="general-purpose")
description: "Analyze [layer] layer"
prompt: |
Use unwind:analyzing-[layer]-layer to analyze this codebase layer.
Entry points from architecture.md:
[entry_points]
SOURCE LINKING - Use this format for all source references:
[link_format from architecture.md]
Replace {path}, {start}, {end} with actual values.
Example: [UserService.ts]([link_format with path=src/services/UserService.ts, start=45, end=67])
IMPORTANT: Write incrementally to folder structure.
1. Create docs/unwind/layers/[layer]/ directory first
2. Write initial index.md with skeleton sections
3. Analyze each section and write its .md file IMMEDIATELY after analyzing
4. Update index.md after each section file is written
5. Do NOT buffer all content for a single write at the end
Output folder: docs/unwind/layers/[layer]/
- index.md (overview + links to sections)
- section files per the skill spec
Follow analysis-principles.md: completeness, machine-readable, link to source, no commentary.
Parallel rules:
- Same phase, no cross-dependencies → parallel
- Wait for phase N before phase N+1
Step 4: Testing Analysis
After application layers complete, dispatch testing specialists in parallel:
- analyzing-unit-tests → unit-tests/ folder
- analyzing-integration-tests → integration-tests/ folder
- analyzing-e2e-tests → e2e-tests/ folder
Testing analysis can reference application layer docs for coverage mapping.
Step 5: Gap Detection Phase
After all layer analysis completes, dispatch verification agents IN PARALLEL to find gaps:
For each analyzed layer:
Task(subagent_type="general-purpose")
description: "Find gaps in [layer] documentation"
prompt: |
Use unwind:verifying-layer-documentation to find gaps in the [layer] layer.
Compare docs/unwind/layers/[layer]/ against source files.
Output ONLY gaps to docs/unwind/layers/[layer]/gaps.md
DO NOT write about what's correct or assign scores.
Gap detection runs in parallel - no dependencies between layers.
Step 6: Gap Completion Phase
After gap detection, dispatch completion agents IN PARALLEL:
For each layer with gaps.md:
Task(subagent_type="general-purpose")
description: "Complete [layer] documentation gaps"
prompt: |
Use unwind:completing-layer-documentation to fix gaps in [layer].
Read docs/unwind/layers/[layer]/gaps.md for the work list.
For each missing item:
1. Read source at specified location
2. Add documentation to specified section file
3. Include [MUST/SHOULD/DON'T] tag
Delete gaps.md when complete.
Completion runs in parallel - no dependencies between layers.
Step 7: Handoff
When completion phase done (all gaps.md files deleted):
Layer analysis complete. Run
unwind:synthesizing-findingsto generate the strategic rebuild plan.
Execution Example
layers:
database: { status: detected, dependencies: [] }
domain_model: { status: detected, dependencies: [database] }
service_layer: { status: detected, dependencies: [domain_model] }
api: { status: detected, dependencies: [service_layer] }
messaging: { status: not_detected }
frontend: { status: detected, dependencies: [api] }
Execution:
- Phase 1:
analyzing-database-layer - Phase 2:
analyzing-domain-model - Phase 3:
analyzing-service-layer - Phase 4:
analyzing-api-layer(messaging skipped) - Phase 5:
analyzing-frontend-layer - Phase 6:
analyzing-unit-tests,analyzing-integration-tests,analyzing-e2e-tests(parallel) - Phase 7: Gap Detection -
verifying-layer-documentationfor all layers (parallel) → gaps.md - Phase 8: Gap Completion -
completing-layer-documentationfor all layers (parallel) - Handoff to synthesis
Refresh Mode
If layer folders exist:
- Pass existing index.md and section files as context
- Subagents add
## Changes Since Last Reviewto index.md
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?