Legacy doc bootstrap

Skill ForeverSc/ai-handrail/skills/legacy-doc-bootstrap

Making Legacy Projects Safer for Vibe Coding. AI适老化改造，让老项目更适合 Vibe Coding。

Install

npx -y skills add ForeverSc/ai-handrail --skill legacy-doc-bootstrap

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when a legacy project needs documentation created from scratch or existing implicit knowledge turned into structured docs. Triggers when user says "document this project", "create docs for this codebase", "write up the architecture", or after legacy-discovery has completed analysis.

SKILL.md

5.6 KB, as published. Nobody here has run it

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

Find existing docs: READMEs, wiki links, inline comments, ADRs, Confluence pages
Evaluate: what's accurate? what's stale? what's missing entirely?
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/<domain-name>/
  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:

Are the business descriptions accurate?
Are any critical areas missing from the domain index?
Are the risk assessments correct?
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/<name>/overview.md`
Module map (per domain)	`templates/module-map.md`	`docs/legacy-modernization/domains/<name>/module-map.md`
Data flow (per domain)	`templates/data-flow.md`	`docs/legacy-modernization/domains/<name>/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/<name>/decisions.md`

Hard Rules

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