Spec doc

Spec Doc

Turn a design/architecture/product decision into a served, visually-communicative HTML spec with a Notion-style margin-comment system (select text → ⌘/Ctrl+M → comment → reply → resolve, persisted to disk). The reviewer marks it up in the browser; you read their comments, amend the doc, reply, and resolve — looping until they're happy.

This skill bundles a zero-dependency engine and a designed template. Your job is to author the content; the engine and look come for free.

What's in assets/

File	Role	How you use it
serve.py	Zero-dep static server + JSON comment API (stdlib http.server; persists to comments.json).	Copy verbatim.
app.js	The comment system: selection anchoring, margin rail, threads, edit/resolve, resolved drawer.	Copy verbatim.
template.html	Self-contained page: full design system (CSS), page shell (topbar / TOC / content / comment rail / drawer), and a complete worked example exercising every component.	Copy → index.html, then replace the article content with the user's spec. Read its top-of-<article> AUTHORING GUIDE comment for the component vocabulary.

Steps

1. Pick a home. Create a folder for the doc, e.g. <repo>/docs/<slug>/. (System-level cross-component docs usually belong under the repo's docs/. If the repo also keeps a markdown spec, this HTML is the reviewable companion — keep both in sync.)

2. Drop in the engine.

   mkdir -p docs/<slug>
   cp <skill>/assets/serve.py docs/<slug>/serve.py
   cp <skill>/assets/app.js   docs/<slug>/app.js
   cp <skill>/assets/template.html docs/<slug>/index.html
   

   (<skill> = this skill's directory.)

3. Author the content. Edit index.html: set <title>, the .toc links, and replace everything inside <article id="doc"> with the spec. This is a real product/tech doc — include the product framing, not just the engineering:

   • Masthead — title, one-line subtitle, status pill (PLANNED / DRAFT / APPROVED), owner, scope.
   • A thesis card — the single core idea in one or two sentences (.thesis).
   • Why — the problem and who it's for. A before/after diagram (.arch) earns its place here.
   • Requirements — functional + non-functional, plus the personas/use-cases that shape the decisions (don't skip this; it's what makes it a product doc).
   • The core idea / architecture — lead with a visual. Use the chart components (.tl timeline, .stack layers, .uni, .life) to make the argument, not decorate it.
   • Tech spec — the concrete code areas to change: a table.tbl of files + what changes, model/schema sketches in .code blocks. Be specific (real file paths, real symbols).
   • Risks — a table with .dot-st status pills (plugged / accepted / flag).
   • Roadmap — phases as a .road track; bracket the recommended first slice (.slice).
   • Open questions — the genuine forks left for the reviewer.

   Use the palette tokens (--terra, --sage, --gold, --coral, --blue) — never hardcode hex. Keep charts hand-built (HTML/CSS/SVG); no chart libraries, no new dependencies. Prefer one well-made figure per section over walls of prose.

   Theming: the default is a warm editorial palette (Fraunces / Hanken Grotesk / JetBrains Mono on cream). If the user wants a different feel, retheme by editing :root and the font <link> — but keep the structure, the comment shell, and the component classes intact.

4. Run + verify (see checklist below). Always verify before handing off — this is what makes the deliverable trustworthy.

5. Tell the user the URL and how to restart, then iterate via comments.

Run & verify (do this every time)

Start it (pick a free port; if one's busy, just try another):

python3 docs/<slug>/serve.py 8791   # or any free port

Then verify — don't assume, check:

• Files parse. python3 -m py_compile serve.py and (if node exists) node --check app.js.
• Server + API end-to-end. curl the page (200, non-trivial size) and /app.js; then create → reply → resolve → list → delete a comment via the API and confirm comments.json reflects each step. (Loop the comment tools via ToolSearch if browser-driving.)
• It renders. Open it in Chrome (claude-in-chrome) and screenshot the top of the page — confirm the masthead, thesis, TOC, charts, and the empty comment rail look right. Known gotcha: deep-scroll screenshots may come back blank — that's a capture-pipeline artifact, not a real bug. Confirm content is actually painted with document.elementFromPoint(x,y) returning real elements rather than trusting a blank frame.
• Comments actually anchor. This is the part screenshots can't prove — drive it programmatically: POST a comment whose anchor.quote is a unique phrase in the doc, reload, and assert exactly one mark.cmt-hl wraps that exact text and a .cmt card renders aligned to it. Also test two comments on the same span → they must share one mark (both ids in data-cid), not corrupt the text.
• Clean up. Delete all test comments so the user opens a clean slate; remove __pycache__.

The review loop

The reviewer selects text and hits ⌘/Ctrl+M to comment; replies and resolves live in the right rail, resolved ones in the drawer. Everything persists to comments.json (the server re-reads it per request, so you can edit it out-of-band while they review).

When they've marked it up:

1. Read comments.json.
2. For each open comment: amend index.html, then reply on that thread (POST /api/comments/<id>/replies with author: "claude" summarizing the change) and resolve it (PATCH resolved: true).
3. Repeat until they're satisfied. Then fold the final state back into any companion markdown spec.

Notes

• Zero dependencies — stdlib http.server only. Never add npm/pip packages for this.
• comments.json is the source of truth and is safe to hand-edit or commit.
• Author comments default to reviewer; use author: "claude" for your own replies so the rail shows the right avatar.