| name | deliver-docs |
| description | Use after a completed epic or significant change to update technical docs and capture resulting decisions or debt. |
Deliver Docs
Usage
Invoke as fiddle:deliver-docs [--epic <id>] [--diff] [--dry-run].
Post-ship documentation update. Reads what changed, updates curated docs, creates ADRs, appends to BACKLOG.
Configuration
Flags (all optional):
--epic <id> — scope to beans under this epic--diff — also read git diff of recent work (default: infer from completed beans)--dry-run — show proposed changes without writing
Docs schema (constraints)
The evolve skill is the authority on doc structure. Apply these constraints to every update.
VISION.md — Under 1 page. Sections: What (1 para), Who (1 para), Success (2-5 signals), Non-goals (bullets), Open questions (bullets). Evolve rarely touches this doc; only flag it if completed work contradicts it.
MARKET.md — Main sections fit one screen. Research log grows unbounded. Only update main sections if work revealed new competitive information. Append to research log if applicable.
PRICING.md — Half page for main sections. Only update if work changed cost structure or revealed pricing-relevant information.
GTM.md — Short. Only update Traction log if a notable event occurred.
SYSTEM.md — 1-2 pages max. Sections: Overview (1 para), Components (entry per component), Data (flows/storage), Infrastructure (where it runs), Invariants (must-be-true), Known issues (specific). This is the primary target of evolve; update it after any architectural change.
RUNBOOKS.md — Commands not prose. Update if deploy process, rollback steps, or common issues changed.
decisions/NNN-title.md — Context (2-3 sentences), Decision (concrete), Consequences (tradeoffs). Create new files, never edit old ones. Supersede with a new record.
BACKLOG.md — Dated entries with origin and tags. Append-only.
Process
1. Gather context
- Read all existing docs in
docs/.
- If
--epic <id>: run beans list --parent <id> --json, read completed beans.
- If no
--epic: run beans list --json, identify recently completed beans.
- Read bean details:
beans show <id> --json for each completed bean.
- If
--diff or if it helps understanding: git log --oneline -20 and git diff for recent changes.
2. Analyze what changed
For each completed bean and its associated changes, classify:
Architectural changes — new components, changed data flows, new dependencies, infrastructure changes, new invariants. → Update SYSTEM.md.
Significant decisions — technology choices, pattern choices, tradeoff decisions that constrain future work. → Create ADR.
Discovered issues — tech debt found during implementation, fragile areas, things that work but shouldn't. → Append to Known issues in SYSTEM.md or to BACKLOG.md.
Ideas surfaced — features or improvements that came up during work but weren't in scope. → Append to BACKLOG.md.
Product implications — changes that affect pricing, positioning, user-facing behavior, or go-to-market. → Flag for manual review, do not auto-update product docs.
3. Propose changes
Present every proposed change to the user before writing. Group by doc:
## SYSTEM.md
- Update Components: added new-service (reason)
- Update Data: changed flow from X to Y
- Add Known issue: description
## decisions/
- New ADR: 003-use-alloydb-over-cloudsql.md
## BACKLOG.md
- Append: idea description (origin: epic-xyz implementation)
## Flagged for review (no auto-update)
- PRICING.md: new service adds $X/month infrastructure cost
- VISION.md: non-goal "no real-time" may need revisiting given new websocket component
4. Write changes
After user confirmation:
SYSTEM.md — Update in place. Follow schema constraints. Keep entries concise. Don't expand sections beyond their purpose. Set Last reviewed: to today.
ADRs — Find highest numbered existing ADR: ls docs/technical/decisions/. Create next number. Use format: NNN-kebab-case-title.md. Follow template: Status: accepted, Context (2-3 sentences), Decision (concrete), Consequences (tradeoffs).
BACKLOG.md — Append new entries at the end. Format: ### YYYY-MM-DD — Title, Description, Origin: tag, hashtag tags.
RUNBOOKS.md — Update if deploy/rollback/common-issues changed. Commands not prose.
Product docs — Flag VISION, MARKET, PRICING, and GTM for manual review instead of auto-updating them. These require deliberate human thinking, not mechanical updates.
5. Verify
After writing:
- Read back each modified file.
- Check that no doc exceeds its schema constraint.
- Check that no research log or append-only entries were deleted.
- Report what was updated.
Rules
- Never update product docs (VISION, MARKET, PRICING, GTM) without explicit user instruction. Only flag.
- Never edit existing ADRs. Create new ones that supersede.
- Never delete append-only entries (FEEDBACK, BACKLOG, research logs).
- Never bloat docs beyond schema constraints. If a section is getting long, suggest splitting or pruning.
- If nothing meaningful changed, say so and stop. Don't create busywork updates.
- Always show proposed changes before writing.
--dry-run skips the write step entirely.
