devflow:foundation:document-legacy-codebase

Document Legacy Codebase

Say exactly: "SKILL INVOKED: foundation/document-legacy-codebase"

Your Role

You are helping the user systematically document a legacy codebase that lacks adequate documentation. Your goal is to make the codebase understandable and maintainable through strategic analysis and clear documentation.

Your Goal

Produce structured documentation that separates concerns correctly:

• CLAUDE.md - Commands, setup, non-obvious gotchas
• .claude/rules/ - Conventions and patterns Claude should follow
• .devflow/architecture.md - System design and component structure
• .devflow/adrs/ - Major architectural decisions (requires user input)

How to Work

Progress:
- [ ] Phase 1: Quick assessment — scan metrics, classify complexity, get approval
- [ ] Phase 2: Generate root CLAUDE.md
- [ ] Phase 3: Component-level rules (one per major component)
- [ ] Phase 4: Architecture documentation
- [ ] Phase 5: Identify ADR candidates
- [ ] Phase 6: Quiz user and draft approved ADRs
- [ ] Phase 7: Review and iterate
- [ ] Phase 8: Update project manifest

Phase 1: Quick Assessment (5-10 minutes)

1. Scan for size and complexity using the codebase-scanner agent (via Task tool):

   • Total LOC by language
   • Directory structure depth/breadth
   • Number of major components
   • Technology stack inventory
   • Entry points discovery

   This is a fast metrics-gathering operation that benefits from context isolation. The agent uses tokei or simple bash commands to gather data without reading code deeply.

2. Classify complexity:

   • Simple (<5k LOC, 1-2 languages): Single-pass analysis
   • Medium (5k-30k LOC, 2-3 components): Component-by-component
   • Large (30k-100k LOC, multi-system): Progressive disclosure
   • Very Large (100k+ LOC, polyglot): Mandatory component-level strategy

3. Present strategy to user:

   • Show metrics and classification
   • Propose analysis strategy (single-pass or progressive)
   • Estimate time required
   • Get approval before proceeding

Phase 2: Generate Root CLAUDE.md (10-15 minutes)

Create lean, imperative documentation:

# [Project Name]

[One-line description from README or package.json]

## Quick Start
[Exact commands to run the project]

## Project Structure
[List major directories with one-line descriptions and pointers to rules files]

## Important Notes
[Non-obvious gotchas, prerequisites, setup quirks]

Critical: Do NOT regurgitate obvious facts. Focus on what Claude can't easily infer:

• ❌ "This is a React project" (Claude can see package.json)
• ✅ "Frontend proxies /api to localhost:8000 in dev"
• ❌ "Uses TypeScript" (Claude can see .ts files)
• ✅ "Type checking disabled in tests/ due to legacy code"

Phase 3: Component-Level Rules (Progressive for Large Codebases)

For each major component (backend, frontend, infrastructure, etc.):

1. Use the component-analyzer agent (via Task tool) to analyze patterns and conventions. When multiple components are identified, run Task tool calls in parallel — one per component:

   • File organization patterns
   • Testing patterns
   • Error handling patterns
   • Common conventions
   • Known gotchas

2. Generate .claude/rules/[component].md:

Follow references/component-analysis-guide.md for structure.

Remember: These are RULES for working with code, NOT architecture descriptions.

Phase 4: Architecture Documentation (15-30 minutes)

Use the architecture-mapper agent (via Task tool) to understand system structure:

• Component identification and responsibilities
• Integration points and data flow
• Technology stack with versions
• Infrastructure topology

Generate .devflow/architecture.md:

• Component diagram (use Mermaid MCP)
• Data flow description
• Integration points
• Technology inventory

Remember: This is DESCRIPTIVE (what exists), not PRESCRIPTIVE (how to work with it).

Phase 5: Identify ADR Candidates (10-15 minutes)

Use the decision-detector agent (via Task tool) to identify major architectural decisions from code:

• Framework/library choices (FastAPI vs Django, React vs Vue)
• Architecture patterns (microservices, event-driven, REST vs GraphQL)
• Infrastructure decisions (PostgreSQL vs MongoDB, Kafka vs RabbitMQ)
• Significant design choices (async patterns, caching strategy, auth approach)

Present candidates to user: "I detected these major architectural decisions in the code:

1. Using Kafka for event processing
2. Using FastAPI with async/await throughout
3. Using React with Zustand for state management
4. Using PostgreSQL with JSONB columns

Should I document any of these as ADRs? (Requires your input on WHY these decisions were made)"

Phase 6: Quiz and Draft ADRs (5-10 minutes per ADR)

For each approved ADR candidate, quiz the user using references/adr-quiz-template.md:

Questions to ask:

1. Why was [technology X] chosen over alternatives?
2. What specific requirements led to this choice?
3. What alternatives were considered?
4. What trade-offs were accepted?
5. Are there constraints this creates for future work?

Draft the ADR combining:

• Context from code analysis (what you observed)
• Rationale from user responses (why it was chosen)
• Consequences and constraints

Get approval before storing.

Phase 7: Review and Iterate

Present summary:

Documentation Generated:
- CLAUDE.md (root)
- .claude/rules/backend.md (FastAPI patterns)
- .claude/rules/frontend.md (React patterns)
- .claude/rules/infrastructure.md (deployment patterns)
- .devflow/architecture.md (system design)
- .devflow/adrs/ADR-001-kafka.md
- .devflow/adrs/ADR-002-fastapi.md
- .devflow/adrs/ADR-003-zustand.md

What am I missing? Should I dive deeper on anything?

Iterate if needed.

Phase 8: Update Project Manifest

Update .devflow/project.md with links to all generated documentation:

documentation:
  claude_md: CLAUDE.md
  rules:
    - .claude/rules/backend.md
    - .claude/rules/frontend.md
    - .claude/rules/infrastructure.md
  architecture: .devflow/architecture.md
  adrs:
    - .devflow/adrs/ADR-001-kafka.md
    - .devflow/adrs/ADR-002-fastapi.md

---

Critical Rules

• Size-aware strategy. Don't try to analyze a 100k LOC codebase in one pass. Use progressive disclosure.
• Separate concerns correctly. Rules ≠ architecture ≠ decisions. Read references/rules-vs-architecture.md.
• CLAUDE.md is lean. Only non-obvious essentials. No regurgitation.
• Rules are prescriptive. "Always do X", "Never do Y", "Tests must..."
• Architecture is descriptive. "System has X components", "Data flows through Y"
• ADRs require human input. You can detect decisions, but only humans know WHY.
• Target 3-7 ADRs max. Only major decisions, not every library choice.
• Use subagents for heavy work. Keep main context for orchestration.
• Get user approval at each phase. Conversational and adaptive.

---

Entry Modes (Auto-Detected)

Detect from context:

• Working directory has source code but no CLAUDE.md → Legacy documentation mode
• .devflow/ already exists → Enhancement mode (add missing docs)
• Multiple major components detected → Recommend progressive strategy

---

Scope Boundaries

This skill produces DOCUMENTATION, not new code.

✅ IN SCOPE:

• Analyzing existing code to understand patterns
• Generating CLAUDE.md and .claude/rules/
• Documenting architecture as it exists
• Capturing ADRs for major decisions (with user input)

❌ OUT OF SCOPE:

• Refactoring or improving existing code
• Writing new features
• Fixing bugs or tech debt
• Enforcing team conventions (that's audit-conventions)

After this skill completes, the user can:

• Use /devflow:build:create-issue to create new work items
• Start the build cycle with better context
• Run /playground to generate an interactive visual code map alongside these docs — useful for navigating the codebase structure in a browser

---

⛔ STOP

Skill complete.