ls-docgen

name

ls-docgen

description

Build a comprehensive current-state developer onboarding wiki for an existing codebase, using existing PRD/architecture docs, build summaries, retrospectives, and the live code itself. Use this skill whenever the user wants to produce documentation that helps developers and onboarding agents quickly understand a system's architecture, design, conventions, and code geography — not how the system was built but how it currently works. Triggers include "build a wiki", "developer onboarding documentation", "current-state docs", "document this codebase", "wiki for our developers and agents", and similar. Strongly prefer this skill over generic markdown-writing approaches when the audience includes both human developers and downstream agents that will consume condensed extracts of the wiki.

Current-State Developer Onboarding Wiki

Produce a wiki that lets developers and onboarding agents grasp a system quickly and drill down to code in one or two hops. The wiki is current-state oriented: it describes what exists, not how it was built. The audience is dual — human developers working in the codebase day to day, and AI agents preparing to plan, design, or review work, including agents that will later read condensed llm.txt extracts of the wiki.

This skill encodes a five-phase workflow with two-stage iterative review, wave-based progression, and parallel subagent drafting. It is designed for non-trivial codebases — typically 10+ wiki pages, multiple top-tier domains, and existing source documentation (PRDs, architecture docs, build summaries, retrospectives) that informs but does not replace the live code as source of truth.

When to use

Use this skill when:

• The user asks to build a developer wiki, onboarding documentation, current-state docs, or a current-state map of an existing system.
• The codebase has existing source documentation (PRD, technical architecture, build summaries, retrospectives, ADRs) that captures intent and history but does not match what was actually built one-to-one.
• The wiki audience includes both human developers and downstream agents.
• The wiki will be substantial enough that subagent-scale drafting is warranted (roughly 10+ pages).

Do not use this skill for:

• Single-page READMEs or one-shot doc updates.
• Methodology guides, tutorials, or marketing material.
• Wikis that document how the system was built (use a history-oriented retrospective format instead).

What this skill produces

A wiki organized into four top-level sections (adjustable per project):

• Current Technical Architecture — the technical world: thesis, stack, top-tier domains, cross-cutting decisions, key runtime flows, known hardening and deferrals.
• Current Technical Design — the codebase by subsystem: domain pages plus cross-cutting infrastructure layers (shared contracts, client surfaces, server control plane, durable state).
• Conventions — universal rules: glossary, repository layout, coding patterns, testing and verification, error codes.
• Reference Material — source docs, build summaries, audits — back-matter, not main reader path.

Each page is written so it stands alone in an llm.txt slice (begins with the system, not the page; carries an architecture recap if it is a domain or design page).

Audience contract

Before doing any work, lock the audience explicitly with the user. The single-audience rule: pick one audience and serve it ruthlessly. The default is developers + onboarding agents both. This rules out:

• Brochure mode — selling the system rather than describing it.
• Kitchen-sink wiki — trying to be all things to all readers (history + arch + user manual + extender guide stapled together).
• Marketing prose — "powerful", "elegant", "modern", "best-in-class".

The wiki describes the system. Every sentence carries technical signal a developer or agent can use.

Five-phase workflow

Each phase has its own reference file. Read the reference file at the start of the phase.

Phase 1 — Orient (read source materials)

Read references/orient.md for the full procedure.

Phase 1 opens with a scan-then-confirm intake: scan the repo for codebase roots and documentation, present an organized inventory to the user, and ask the user to confirm scope (use everything found / use everything except specific items / use only explicit items / add anything missing). Then read the confirmed source materials in disciplined chunks, sequentially, with reflection between chunks.

By the end of Phase 1 you have:

• A locked audience contract
• A confirmed list of source documents to read (and have read)
• An understanding of the platform's 3–8 top-tier domains
• An understanding of what NOT to include (history, brochure framing, deferrals as main content)

Phase 2 — Shape (skeleton + briefing infrastructure)

Read references/shape.md for the full procedure.

Phase 2 produces:

• A picked section structure (typically architecture / design / conventions / reference)
• A picked design-page split (typically hybrid: domain pages + cross-cutting infrastructure layers)
• Skeleton files for every page (validates navigation before drafting)
• A wave plan (typically 4 waves: foundational anchors → architecture body → design + remaining conventions → cross-page polish)
• A customized agent-brief.md artifact in the project's _drafting/ directory (copied from assets/agent-brief-template.md and filled in for this project)

Phase 2 ends with a second-opinion review of the skeleton and the agent-brief before any per-page briefs are drafted.

Phase 3 — Brief and review (per wave)

Read references/briefing.md and references/review.md.

For each wave:

1. Draft per-page briefs (one per page) using assets/per-page-brief-template.md as the master shape, customized per page.
2. Self-review against the universal principles in references/principles.md.
3. Second-opinion review of the briefs before subagent dispatch. Catches brief over-specificity (fictional pre-lists, misnamed services, wrong shadowing rules) before agents amplify across drafts.
4. Apply fixes.

Phase 4 — Dispatch (per wave)

Read references/dispatch.md.

Spawn Opus subagents in parallel, one per page. Each prompt follows assets/dispatch-prompt-template.md. The single most important instruction in every prompt is "live tree wins over the brief; surface deviations in your return summary".

Receive drafts and return summaries. Each agent reports word count, deviations from the brief and reasons, and items for the next reviewer.

Phase 5 — Review (per wave + cross-wave polish)

Read references/review.md.

For each wave's drafts:

1. Fresh-eyes review pass — either new agents loaded into fresh contexts or main-agent re-read.
2. Second-opinion review — user runs a verifier (recommend gpt-5.4 high or gpt-5.5 low) on the same materials with verifier mindset.
3. Evaluate findings, agree or push back, apply fixes.
4. Bake lessons forward into the next wave's briefs.

After all waves complete, run a final cross-wave polish pass: reconcile drift between sections (terminology, freshness reasons, error codes), tighten the wiki home page against canonical wording from architecture pages, address deferred P3 items.

Six review-point cadence

The skill encodes six review points minimum, correlating with the cadence used in the reference build that produced this skill:

1. After audience + scope decision (Phase 1 close) — confirms the wiki frame before anything is built.
2. After skeleton + section structure (Phase 2 mid) — confirms the page list and section split before drafting begins.
3. After shared agent-brief.md drafted (Phase 2 close) — the universal-standards artifact every agent will read.
4. Per wave: after per-page briefs drafted, before subagent dispatch (Phase 3 close per wave) — catches brief over-specificity before amplification.
5. Per wave: after drafts return (Phase 5 mid per wave) — catches factual drift in actual drafted pages.
6. After cross-wave polish (Phase 5 close) — final consistency / drift reconciliation.

The recommended pattern: Opus orchestrates with the user; the user runs a second-opinion verifier (gpt-5.4 high or gpt-5.5 low via Codex CLI or equivalent) on the same materials with verifier mindset; the user pastes findings back; Opus evaluates each finding, agrees or pushes back with reasoning, applies fixes. Skip none of the six review points. Skipping once means the next wave's briefs inherit unflagged issues.

Wave model

The wiki is drafted in waves, not all at once. Waves serve two purposes:

• Vocabulary anchoring — later pages link to glossary terms and repo paths defined in earlier pages. Drafting glossary first prevents agents from inventing variants in subsequent waves.
• Lessons forward — issues caught in wave N's review become brief instructions in wave N+1.

Default wave structure:

Wave	Pages	Why first or last
1 — Foundational anchors	Glossary, repository layout, wiki home	Every other page links to glossary terms and the repo path map. Home page sets reader paths.
2 — Architecture body	Architecture overview, top-tier domains, core stack and runtime surfaces, cross-cutting decisions, key runtime flows, known hardening and deferrals	Establishes the canonical world that design pages drill into.
3 — Design + remaining conventions	Design overview, infrastructure layer pages, domain pages, coding patterns, testing and verification, error codes	The largest wave; concrete drilldown into the codebase.
4 — Cross-wave polish	No new pages	Reconciles drift, tightens home page against canonical wording, addresses deferred items.

Adjust the wave count and contents based on project size. Smaller projects may collapse waves 2 and 3 into one parallel dispatch; larger projects may split wave 3 into sub-batches. The vocabulary-first-then-bodies rule is invariant.

Eight key decision points

The skill surfaces eight decisions the user makes during a project. Most are made early in Phase 1 or Phase 2 and stay locked through the build.

1. Audience contract — who reads this wiki (default: developers + agents both, single audience).
2. Source materials inventory — which docs are authoritative; what to exclude; what's missing.
3. Section structure — which top-level sections (default: architecture / design / conventions / reference).
4. Design-page split — pure domain pages, pure infrastructure layers, or hybrid (default: hybrid when the wiki spans both platform behavior and code geography).
5. Wave count and order — usually 4 (anchors / architecture / design+conventions / polish); adjustable.
6. Subagent batching — single parallel dispatch vs sub-batches per wave (default: single parallel dispatch up to ~15 agents).
7. Anti-patterns artifact lift — keep anti-patterns folded into the principles artifact, or lift them into a separate project-side artifact (rule of thumb: lift when project will produce 5+ pages and span multiple waves).
8. Polish-pass gating — what counts as "wiki is done" (default: all six review points cleared, no open P1/P2 findings, cross-page consistency reconciled).

Two-layer template model

The skill ships master templates in assets/. The user (or Opus following the skill) copies and customizes them into the project's _drafting/ directory at the start of Phase 2. Subagents read the customized project artifacts from disk during Phase 4.

Layer	Lives at	Changes per project?
Master template	assets/ of the skill	No — reusable scaffold
Project artifact	<project>/_drafting/	Yes — customized for this codebase

This matters because:

• Master templates encode hard-won structural decisions (the per-page brief field set, the verification checklist pattern).
• Project artifacts encode project-specific facts (domains, forbidden vocab, source materials, wave structure).
• Subagents reading from a single canonical project path is what keeps parallel dispatch coherent.

Templates to copy at Phase 2 start:

• assets/agent-brief-template.md → <project>/_drafting/agent-brief.md
• assets/per-page-brief-template.md → kept as reference; per-page briefs created from it as needed (one per page per wave, written into <project>/_drafting/wave-N/<page-slug>.md)
• assets/dispatch-prompt-template.md → kept as reference; dispatch prompts assembled from it inline at dispatch time

Universal principles

Read references/principles.md before Phase 2 and re-read whenever drafting a brief or evaluating a draft. The principles apply across the entire wiki and are baked into every brief and prompt:

• Live code wins over brief; surface deviations
• Forbidden meta-vocabulary (no methodology terms in artifacts)
• Standalone opening / Architecture Recap pattern
• Canonical diagram arrow lists
• Advisory tone
• Bespoke depth
• Source-of-truth precedence (live code → standup reviews/audits → original PRD/arch)

references/principles.md also includes an Anti-patterns section with the eight failure modes most worth guarding against.

Pointers to references

Situation	Read
Starting Phase 1	references/orient.md
Starting Phase 2	references/shape.md
Drafting a wave's per-page briefs	references/briefing.md
Dispatching subagents for a wave	references/dispatch.md
Reviewing briefs or drafts	references/review.md
Drafting any artifact	references/principles.md (always)

The references are deliberately compact. SKILL.md gives you the workflow; references give you the procedures.