gg-skill-doc

GG-SKILL-DOC — Living Project Documentation Generator

Reads every artifact produced by the gg-skill-* pipeline and synthesizes them into a single, human-readable doc.md — the authoritative reference for onboarding, stakeholders, and cross-team handoffs.

The document is derived from sources, never invented. Every claim traces back to a file.

---

Input Modes

Mode	Trigger	What happens
Full generation	No args (or -o PATH)	Collect all artifacts → synthesize doc.md
Update	-update	Re-read only changed files (git diff since last doc.md write) → patch affected sections
Section filter	-sections LIST	Generate only named sections (comma-separated, e.g. -sections api,security)
Phase focus	-p N	Include only phases up to N in roadmap and testing sections
Output	-o PATH	Custom output path (default: doc.md at project root)
Language	-language LANG	Default English. Code, file paths, identifiers kept as-is.

---

Phase 0 — Source Discovery

Scan project root and standard paths. Record found vs. absent. Never block on a missing file — degrade gracefully and note the gap.

Priority: patched > original

Artifact	Preferred	Fallback
PRD	PRD-patched.md	PRD.md
Architecture	architecture-patched.md	architecture.md
Phase spec N	docs/phases/phaseN.md	—
Phase dev N	docs/dev/phaseN.md	—
Phase enhancement N	docs/dev/phaseN-enhancement.md	—
Recette index	recette.md	—
Recette phase N	recette_phaseN.md	—
Dep-tree	dep-tree.md	—
PRD enhancement	PRD-enhancement.md	—
Arch enhancement	architecture-enhancement.md	—

Discovery output (in chat only, not in doc.md):

## Source Discovery

PRD:              ✅ PRD-patched.md
Architecture:     ✅ architecture-patched.md
Dep-tree:         ✅ dep-tree.md (Phase 3, 2025-03-20)
Phase specs:      ✅ Phase 1  ✅ Phase 2  ⚠ Phase 3 (spec only, no enhancement)
Recette:          ✅ recette.md  ✅ Phase 1  ✅ Phase 2  ❌ Phase 3

Gaps noted — affected sections will show [SOURCE MISSING] markers.

---

Phase 1 — Extraction Rules

Read each source silently. Extract only what the schema requires. Do NOT invent values not present in sources.

Full extraction rules per source in references/extraction-rules.md.

Key rules:

• From PRD: KPIs, personas, MVP scope, user stories, tech stack, risk register, phase roadmap
• From Architecture: style, C4 diagrams (copy verbatim), ADRs, data models, auth flow, rate limits
• From Phase Specs: phase goals, sprint list, exit criteria, SH-1 invariants
• From Phase Enhancements: accepted debt (D-* items), remaining weaknesses
• From Recette files: scenario counts (P0 / P1–5 / total), PASS/FAIL/PENDING, last run date
• From dep-tree.md: freshness header, top 5 most-used modules, high fan-in/fan-out nodes
• From Enhancement Agent Status Blocks: confidence_score.global, ready_for_architecture, ready_for_senior_specs, open blocking_issues

---

Phase 2 — Write doc.md

Output path: -o value, or doc.md at project root.

Every section is mandatory unless marked (if applicable) or source is absent (use [SOURCE MISSING — run /gg-skill-{command} to fill]).

Full section templates in references/doc-schema.md.

13 sections:

#	Section	Key sources
1	Project Overview + Pipeline Health	PRD, PRD-enhancement.md, architecture-enhancement.md
2	Target Users	PRD Section 3 (personas)
3	Architecture Overview	architecture Section 1–3, 11 (ADRs)
4	Data Model	architecture Section 5 (ERD, data stores, flows)
5	API Reference	architecture Section 7 (errors, auth flow, rate limits)
6	Features & User Stories	PRD Section 4–5 (MVP scope, user stories)
7	Phase Roadmap & Status	PRD Section 11, recette_phaseN.md, phaseN-enhancement.md
8	Infrastructure & Deployment	architecture Section 8 (envs, CI/CD, observability)
9	Security	architecture Section 9, PRD Section 9
10	AI Architecture (if applicable)	architecture Section 6
11	Risk Register	PRD Sections 10, 12, 13, enhancement blocking_issues
12	Codebase Map (if dep-tree present)	dep-tree.md
13	Tech Stack Summary	PRD Section 6, architecture Section 5.2

Diagrams: Copy C4 diagrams, ERD, and data flows verbatim. Do not redraw or summarize them.

---

Phase 3 — Post-Write Validation

After writing doc.md, output in chat (not in the file):

## doc.md Validation

Sections written:     {N}/13
[SOURCE MISSING] markers: {N}
  → {list each missing source and which section it affects}

Phases covered:       Phase 1 … Phase N
Recette coverage:     {N}/{N} phases have recette data
Open blocking issues: {N} (see Section 11)

doc.md written to: {path}
Word count: ~{N} words

{IF any [SOURCE MISSING]:}
Run the corresponding command to fill gaps:
  - Missing PRD → /gg-skill-prd
  - Missing architecture → /gg-skill-architecture {PRD path}
  - Missing phase spec N → /gg-skill-specs N
  - Missing recette N → /gg-skill-recette -p N
  - Missing dep-tree → /gg-dep-tree

{IF all sourced:}
✅ doc.md is fully sourced.

---

Update Mode (-update)

Step 1 — Find changed files:

git diff --name-only {doc.md last-modified date}

Step 2 — Map changed files to sections:

Changed file	Sections affected
PRD-patched.md	1, 2, 6, 7, 11, 13
architecture-patched.md	3, 4, 5, 8, 9, 10, 12, 13
docs/phases/phaseN.md	7 (phase N row)
docs/dev/phaseN-enhancement.md	7 (debt), 11 (blocking)
recette_phaseN.md	7 (phase N recette table)
dep-tree.md	12
PRD-enhancement.md	1 (Pipeline Health), 11 (blocking)
architecture-enhancement.md	1 (Pipeline Health), 11 (blocking)

Step 3 — Patch only affected sections. Preserve unchanged sections verbatim.

Step 4 — Update footer (generation date, source list).

Output in chat:

## Autoupdate — {datetime}

Changed files detected: {N}
Sections patched: {list}
Sections unchanged: {list}

doc.md updated: {path}

---

Section Filter (-sections LIST)

Accepted names (case-insensitive): overview, users, architecture, data-model, api, features, roadmap, infrastructure, security, ai, risks, codebase, stack.

Header and footer are always included regardless of filter.

---

DO / DON'T

DO:

• Always prefer *-patched.md over originals — they are the authoritative versions
• Copy diagrams verbatim — do not redraw or summarize them
• Mark gaps with [SOURCE MISSING — run /gg-skill-{command} to fill]
• Include the Pipeline Health table even when confidence is low — that IS the information
• Flag stale dep-tree explicitly (current phase > dep-tree phase)

DON'T:

• Invent KPIs, acceptance criteria, or risk scores not in sources
• Merge or paraphrase ADRs — copy the choice and trade-off verbatim
• Omit the footer — it is the traceability record
• Generate Phase N+1 content if Phase N spec does not exist
• Summarize recette files without counting scenarios — the numbers matter

---

Workflow Position

gg-skill-prd
    ↓ PRD-patched.md
gg-skill-architecture
    ↓ architecture-patched.md
gg-skill-specs (per phase)
    ↓ docs/phases/phaseN.md
gg-dep-tree
    ↓ dep-tree.md
gg-skill-phase (per phase)
    ↓ code + dep-tree updated
gg-skill-recette (per phase)
    ↓ recette_phaseN.md
gg-skill-doc              ← you are here
    ↓
doc.md  ← living document, re-run after each phase

Run gg-skill-doc -update after every phase close to keep doc.md current with minimal re-generation.