| name | bolt-retrospective |
| description | Structured post-Bolt retrospective that captures process improvements, proposes constitution amendments, and updates bolt-* skills. Targets the development process — not the project. Distinct from bolt-synthesis. |
Bolt-Retrospective Workflow: Process Improvement
This workflow improves the development process — not the project artifacts. Run it after one or more Bolts are merged, or at a regular cadence (every 3–5 Bolts). It is the closed feedback loop that prevents recurring friction from becoming permanent overhead.
Distinction from bolt-synthesis: bolt-synthesis asks "what did we learn about the project?" and updates ARCHITECTURE.md / CONVENTIONS.md. bolt-retrospective asks "what did we learn about the process?" and proposes changes to constitution.md or the bolt-* skills themselves.
When to Run
- After a Bolt that surfaced significant or recurring process friction.
- After every 3–5 Bolts as a regular cadence check.
- Before starting a new major initiative or phase.
1. Evidence Collection
For each Bolt under review, gather the following artifacts:
plan.md — compare planned task count and complexity against what actually occurred.implementation_decisions.md — catalogue all runtime deviations and their root causes.audit-report.md — note residual risks, known limitations, and rework items that originated in the process.research.md (if present) — was research sufficient? Were architecture decisions later revised?- Chat / session context — identify recurring blockers, repeated clarifications, or steps that were skipped.
2. Pattern Analysis
Synthesize the evidence into process signals:
- Plan accuracy: Were tasks under- or over-scoped? Were dependencies missed during
bolt-intent?
- Recurring blockers: Did the same type of ambiguity, missing research, or absent convention appear in multiple Bolts?
- Skipped steps: Which workflow steps were skipped, and was the reason documented or silent?
- Constitution compliance: Were any articles violated? Were violations justified and logged?
- Skill effectiveness: Did any bolt-* skill prompt cause confusion, ambiguity, or incorrect agent behavior?
3. Produce retrospective.md
Generate docs/design/retrospective-YYYY-MM-DD.md (for batch reviews) or docs/design/<feature-name>/retrospective.md (for single-Bolt reviews):
---
scope: [feature-name, other-feature, ...] # Features reviewed
date: YYYY-MM-DD
status: draft
---
# Retrospective
## What Worked
- <Process steps that accelerated delivery or prevented rework, with evidence>
## What Didn't
- <Friction point> — **Root cause**: <cause>
## Proposed Changes
### Constitution Amendments
| Article | Proposed Change | Rationale |
|---------|----------------|-----------|
### Bolt Skill Improvements
| Skill | Section | Proposed Change | Rationale |
|-------|---------|----------------|-----------|
### New Conventions
- <Convention to add to CONVENTIONS.md via bolt-synthesis>
4. Action Gate
Present retrospective.md to the user. For each proposed change:
- Constitution amendments: If approved, invoke
bolt-constitution amendment protocol. The amendment is logged in constitution.md and the version is incremented.
- Bolt skill improvements: If approved, update the relevant skill file(s) directly.
- New conventions: If approved, these are handed to
bolt-synthesis for incorporation into global project documentation.
Update frontmatter to status: approved once all actions are resolved.
Next Steps: Resolved convention changes feed into bolt-synthesis. Approved constitution amendments trigger bolt-constitution. Approved skill changes are applied to the relevant bolt-*/SKILL.md files.
