Skip to content

A worked example — the site you are reading

The docs site serving you this page was built through the exact pipeline you just learned, as slug 2026-06-05-spec-docs-site. Every artifact below is real; the commit SHAs are in developers-environment history. This page narrates it honestly — including the part where a critic blocked the plan and won.

1. The ask, classified

A developer said: "we could serve all the specs as an online site, with a Start Here tutorial." No spec described a docs site → Shape 1. The router proposed /sdd-plan; the human approved.

2. The staged proposal (/sdd-plan, commit 671d871)

The natural home was a new publishing section of platform.spec-governance — the spec that already declared GitLab a generated projection of the index; a docs site is the same idea pointed at humans. The skill staged the full proposed section, the apply manifest, and the Before/After commentary on branch sdd/2026-06-05-spec-docs-site. The canonical spec was not touched — as you read this, the publishing section of platform.spec-governance is the applied result.

3. Gaps become tickets (/sdd-spec-gap)

The gap sweep read the staged section as spec-of-record and found everything greenfield: no generator, no mkdocs config, no CI, no tutorial. It wrote gap items platform-spec-governance-01..04 into specs/dev-plan/ — the canonical tickets — and adopted them in-progress.

4. Tasks, then implementation with critics

/sdd-task-plan split the work into six one-commit tasks (T1 generator … T6 deploy manifests), each with a runnable criterion. Then, per task, /sdd-implement ran test-first with the three critics. Highlights:

  • T1 (generator, commit 6505295): the risk critic forced atomic temp-dir+swap output (a failed build can never publish a partial site) and caught that the build output directory wasn't gitignored in a repo where a bot auto-commits.
  • T2 (cross-links, commit 2137484): the risk critic returned block — it had checked the live corpus and proved the planned hard-fail on broken references would break the pipeline on day one, because seven-plus existing specs already carried broken id references. The resolution amended the staged proposal (that's what staging is for): unresolved references warn by default, a --strict-refs flag escalates, and the discovered rot became a ledger entry plus follow-up gap platform-spec-governance-05.
  • T3 (mkdocs + Pages CI, commit 95d618c): post-build HTML verification caught the anchor rewriter mutating documented anchor examples inside code fences — a bug no unit fixture had provoked. Fence-awareness landed with a regression test.
  • T4 is the page you are reading.

5. Review, ship, apply

/sdd-review certified the slug against the staged spec; /sdd-ship pushed branches, opened MRs, gated on CI, merged; the shipper ran sdd_apply_staged.py, which verified the all-merged barrier and pushed §publishing into the canonical platform.spec-governance. The staging directory was then dropped — its story survives in the MR, the applied spec, and this page.

What the example teaches

  • The spec edit preceded every line of code, and was itself revised under critique — the golden state is negotiated, not decreed.
  • The critics blocked twice and were right twice; both catches were invisible from inside the plan.
  • Bypasses and deferrals (warn-tier, ship-time checklists, corpus rot) were recorded as work, never silently absorbed.

What you can do now

  • Run the loop on something small: a one-line clarification to a spec you own, through /sdd-plan → /sdd-spec-gap → /sdd-implement → /sdd-ship.
  • When your plan gets blocked, re-read step 4 above — then revise the staged proposal or rebut with evidence, exactly as happened here.