Process Β· Tooling
Skills & Commands
The repeatable engineering rituals: a skill to follow every time before publishing docs, and a slash command to review every feature in one pass.
Where they live
| Artifact | Path | Invoke |
|---|---|---|
Skill β publish-doc | .claude/skills/publish-doc/SKILL.md | Auto-triggers on doc changes / "publish the docs"; or run via the Skill menu |
Command β /review-features | .claude/commands/review-features.md | Type /review-features (optionally /review-features payments) |
The publish-doc skill β follow every time
A blocking checklist that keeps every page identical, every diagram rendering, every link valid, and the resumable plan honest. Summary of the gates:
- Shared assets only β link
ridechain.css+ridechain.js+ Mermaid CDN; no inline styles; correct../depth. - Consistent chrome β topbar, sidebar, footer byte-identical to a sibling; own sidebar link present; title/description/breadcrumb set.
- Diagrams β every diagram in
.rc-figure > pre.mermaidwith a caption; valid Mermaid; verify it renders (no syntax-error box). - Content bar β ToC,
.rc-tablewrappers, callouts, and a real "Edge cases & failure modes" section cross-linked to the catalog. - Links & integrity β run the link scan; zero broken internal links.
- Update the plan β set this doc's status chip in plan.html and refresh the resume banner.
- Commit/push only if asked β docs generation is authorized; git is not, unless the user says so.
Why a skill? Publishing consistency is a rule that must fire every time, automatically β exactly what a skill is for. The full machine-readable checklist (with verification commands) lives in
.claude/skills/publish-doc/SKILL.md.Verification commands (from the skill)
flowchart LR
A["βοΈ Edit / create doc"] --> B["publish-doc skill"]
B --> C{"Assets Β· chrome Β·
diagrams Β· links OK?"}
C -- no --> A
C -- yes --> D["Update plan.html
status + resume banner"]
D --> E{"User asked
to commit?"}
E -- no --> F["β
Published locally"]
E -- yes --> G["Branch β stage docs/
β commit β report"]
classDef g fill:#e7f4ec,stroke:#1b7f4b,color:#115c36;
class A,B,D,F,G g;
The two scans the skill runs (see the SKILL.md for the full text):
- Broken-link scan β a small Python pass over
docs/**/*.htmlthat resolves every internalhref="β¦β.html"and reports any that don't exist. - Asset wiring check β greps every page for
ridechain.cssandridechain.jsto catch a page that forgot the shared assets.
Render, don't just grep. The grep confirms wiring only. To confirm Mermaid actually parses, open the page in a browser (or drive it with Playwright via the
verify skill) and confirm no red "Syntax error in text" box appears in any figure.The /review-features command β audit everything
Runs a completeness, consistency and edge-case audit across the whole product surface (or a single feature if you pass an argument). It fans out parallel review agents β one per feature cluster β then synthesizes a single ranked findings table.
| It checks, per feature⦠| And reports |
|---|---|
| Documented? has a diagram? has an edge-case section? | Coverage verdict |
| Money numbers, entity names, vehicle types, OTP/POD & routing rules match across docs? | Consistency β flags contradictions |
| Which failure modes are missing or under-specified? | Edge-case gaps list |
| Broken links, missing assets, unparseable Mermaid? | Integrity issues |
| Overall | β / π‘ / π΄ verdict + top-3 fixes |
Usage:
/review-features οΌ audit all features /review-features payments οΌ scope to one feature/component
Cadence. Run
/review-features after a batch of docs lands and before any product milestone, and run the publish-doc skill on every individual page. Together they keep the docs trustworthy as the source of truth for the build.Edge cases & failure modes
| Risk | Mitigation |
|---|---|
| Page drifts from shared style (inline CSS creeps in) | publish-doc gate #1 forbids inline styles; review flags it |
| Sidebar diverges across pages | publish-doc requires byte-identical chrome vs a sibling |
| Mermaid silently fails to render | Browser/Playwright render check, not just grep |
| Plan board goes stale β not resumable | publish-doc gate #6 forces status + resume-banner update |
| Money figures contradict between docs | /review-features consistency pass cross-checks commission/split/payments |
The exhaustive product failure-mode catalog is in Edge-Case Catalog.