Legacy Doc Bootstrap

Legacy Doc Bootstrap

Turn implicit project knowledge into structured, AI-consumable documentation — many small focused files, never one giant doc.

Goal

Produce a documentation set that enables any AI session (including future ones with no conversation history) to safely understand and work within this project.

When to Use

• After legacy-discovery has produced initial analysis
• When starting to document an undocumented legacy project
• When existing docs are stale, incomplete, or scattered
• When onboarding info only exists in people's heads

Mandatory Workflow

Step 1: Assess Current Documentation State

1. Find existing docs: READMEs, wiki links, inline comments, ADRs, Confluence pages
2. Evaluate: what's accurate? what's stale? what's missing entirely?
3. Map gaps against discovery outputs — what knowledge exists only in the discovery analysis?

Step 2: Create Map Layer (if not exists)

Create the top-level index files in docs/legacy-modernization/:

00-overview.md              — project purpose, tech stack, high-level architecture
01-domain-index.md          — list of business domains with brief descriptions
02-critical-path-index.md   — P0 user journeys with entry points and key files
03-dependency-audit.md      — framework/library versions, known constraints
04-glossary.md              — project-specific terms, abbreviations, acronyms

These are index/summary files. Keep each under 200 lines. They point to detail docs.

Step 3: Create Domain Detail Docs

For each domain analyzed by discovery, create:

docs/legacy-modernization/domains//
  overview.md         — what this domain does, who owns it, current state
  module-map.md       — files/modules in this domain, their responsibilities
  data-flow.md        — how data moves through this domain
  risks.md            — known risks, tech debt, fragile areas
  test-baseline.md    — current test coverage, gaps, testing strategy
  decisions.md        — past architectural decisions, trade-offs made

Step 4: Create Shared Docs

docs/legacy-modernization/shared/
  compatibility-rules.md   — version constraints, API compatibility notes
  risk-registry.md         — consolidated risk list across all domains

Step 5: Validate with Human

Present the generated documentation structure to the user. Ask:

1. Are the business descriptions accurate?
2. Are any critical areas missing from the domain index?
3. Are the risk assessments correct?
4. What implicit knowledge should be added?

Required Outputs

| Output | Template | Location | |--------|----------|----------| | Project overview | templates/project-overview.md | docs/legacy-modernization/00-overview.md | | Domain overview (per domain) | templates/domain-overview.md | docs/legacy-modernization/domains//overview.md | | Module map (per domain) | templates/module-map.md | docs/legacy-modernization/domains//module-map.md | | Data flow (per domain) | templates/data-flow.md | docs/legacy-modernization/domains//data-flow.md | | Risk registry | templates/risk-registry.md | docs/legacy-modernization/shared/risk-registry.md | | Dependency audit | templates/dependency-audit.md | docs/legacy-modernization/03-dependency-audit.md | | Human decisions log | templates/human-decisions.md | docs/legacy-modernization/domains//decisions.md |

Hard Rules

1. Many small files. No single doc over 300 lines. Split by topic.
2. Stub-first is fine. Create the file structure with [TODO] placeholders. Fill progressively.
3. Single responsibility. Each doc answers one question (what does this module do? how does data flow? what are the risks?).
4. Facts only. Don't speculate. Mark uncertain info as [UNVERIFIED] or [NEEDS-HUMAN-REVIEW].
5. Include versions. When referencing libraries/frameworks, always include the actual version from lockfile.
6. Link, don't duplicate. If info exists in another doc, link to it.
7. Keep maps navigable. Index files must have working links to detail docs.
8. Document non-standard behavior explicitly. Hidden traps, counter-intuitive flows, and accidental side effects need a dedicated note, not a vague warning.
9. Use flowcharts for complex logic. data-flow.md should include a flowchart whenever prose would hide branching or state transitions.
10. Record dependency verification evidence. High-impact old dependencies need a note of whether source inspection was performed.

Anti-Patterns

| Don't | Do instead | |-------|------------| | Write a 2000-line architecture doc | Split into focused files per template | | Document everything in round one | Start with P0 domains, expand progressively | | Copy-paste discovery outputs as-is | Transform analysis into structured templates | | Document things you haven't verified | Mark as [UNVERIFIED] with source reference | | Skip the glossary | Domain jargon trips up both AI and new humans | | Write docs that only make sense with chat context | Docs must be self-contained and context-free |

Progressive Documentation Strategy

Round 1: Map layer + one domain detail set (the most critical domain) Round 2: Second domain + refine round-1 docs based on new understanding Round 3+: Expand coverage domain by domain

Each round should also revisit and correct earlier docs as understanding improves.

Source & license

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

• Author: ForeverSc
• Source: ForeverSc/ai-handrail
• License: MIT

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