record-decision
npx machina-cli add skill hardness1020/VibeFlow/record-decision --openclawrecord-decision
Document ADRs for non-trivial choices at Stage D of the VibeFlow docs-first workflow.
Purpose
This skill creates ADR (Architecture Decision Record) documents for Stage D:
- Document non-trivial architectural decisions
- Record alternatives considered and consequences
- Include rollback plans
Workflow
Stage D: Decide
│
├── Create ADRs for non-trivial decisions
├── Document alternatives and consequences
└── Include rollback plans
Usage
Create ADR
/record-decision <ID> <slug>
Creates docs/adrs/adr-<ID>-<slug>.md.
Example:
/record-decision 001 backend-framework
Document Requirements
ADR (docs/adrs/adr-<ID>-<slug>.md)
Required sections:
- Title with decision summary
- Header (File, Status)
- Context
- Decision
- Consequences (+/-)
- Alternatives
- Rollback Plan
- Links (PRD/SPEC/FEATURE references)
Validation
scripts/validate_adr.py— Validate ADR
References
See assets/:
adr-template.md— ADR template
Manifest Update
After completing Stage D, update docs/workflow-state.yaml:
- Set
stage: D - Append to
docs.adrs[]:docs/adrs/adr-<ID>-<slug>.md
Checkpoint #1 (after Stage D):
- Set
checkpoint: 1after passing validation - Criteria: PRD exists with all required sections, discovery doc exists, at least one tech spec, at least one ADR
To check readiness: /validate-checkpoint 1
To advance to the next stage: /manage-work advance <ID>
Source
git clone https://github.com/hardness1020/VibeFlow/blob/main/.claude/skills/record-decision/SKILL.mdView on GitHub Overview
This skill guides you to document Architecture Decision Records (ADRs) for non-trivial choices at Stage D of the VibeFlow docs-first workflow. It ensures decisions, alternatives, consequences, and rollback plans are captured, linked, and validated. ADRs are stored under docs/adrs/adr-<ID>-<slug>.md and tracked through the workflow state.
How This Skill Works
When invoked, the command creates an ADR file at docs/adrs/adr-<ID>-<slug>.md using the ADR template. You populate required sections (Title, Context, Decision, Consequences, Alternatives, Rollback Plan, Links). Validate with scripts/validate_adr.py, then update the workflow state and checkpoint as you progress toward completion.
When to Use It
- When you face a non-trivial architectural decision during Stage D of the docs-first workflow
- When you need to compare alternatives and explicitly record their consequences
- When a rollback plan is required before finalizing a decision
- When you must reference PRD/SPEC/FEATURE in the ADR
- When you want to validate the ADR with the tooling and advance to the next stage
Quick Start
- Step 1: Run /record-decision <ID> <slug> to create the ADR at docs/adrs/adr-<ID>-<slug>.md
- Step 2: Fill in Title, Context, Decision, Consequences, Alternatives, Rollback Plan, and Links
- Step 3: Validate with scripts/validate_adr.py and update the workflow state (checkpoint 1) using /validate-checkpoint 1 and/or /manage-work advance <ID>
Best Practices
- Limit ADRs to non-trivial decisions with broad impact
- Document alternatives and consequences clearly and objectively
- Include a explicit rollback plan for safe rollback
- Use the ADR template from assets/adr-template.md and maintain consistent structure
- Validate ADRs with scripts/validate_adr.py and update docs/workflow-state.yaml accordingly
Example Use Cases
- 001 backend-framework
- 002 database-choice
- 003 auth-flow
- 004 messaging-queue
- 005 caching-strategy
