vibe-decision-journal
Scannednpx machina-cli add skill ash1794/vibe-engineering/decision-journal --openclawFiles (1)
SKILL.md
1.7 KB
vibe-decision-journal
Record decisions so future-you (or future-Claude) doesn't re-debate settled questions.
When to Use This Skill
- After choosing a technology, framework, or pattern
- After making an architectural decision
- After deciding NOT to do something (negative decisions are valuable)
- When you realize "we keep coming back to this question"
When NOT to Use This Skill
- Trivial implementation choices (variable naming, formatting)
- Decisions already documented in the project's ADR or design docs
- Temporary/reversible choices (which test to run first)
Steps
- Capture the decision in ADR format:
## Decision: [Short title]
**Date**: [Today]
**Status**: Accepted
### Context
[What situation prompted this decision? What constraints exist?]
### Decision
[What did we decide? Be specific.]
### Alternatives Considered
1. [Alternative A] — Rejected because [reason]
2. [Alternative B] — Rejected because [reason]
### Consequences
- [Positive consequence]
- [Negative consequence / trade-off]
### Affected Files
- [path/to/file.ext]
-
Store it — Use one of:
- MCP memory (if available):
mcp__plugin_claude-mem_mcp-search__save_memorywith title "DECISION: [topic]" - Project file: append to
docs/decisions/ordocs/adr/ - Memory file: append to Claude's auto-memory
- MCP memory (if available):
-
Cross-reference — If this decision affects other decisions, note the connections.
Output Format
Present the ADR to the user for confirmation before saving. Keep it concise — 10-20 lines max.
Source
git clone https://github.com/ash1794/vibe-engineering/blob/master/skills/decision-journal/SKILL.mdView on GitHub Overview
This skill records architectural and technology decisions in ADR format to enable cross-session persistence. It helps future-you (or Claude) avoid re-debating settled questions by providing a concise, traceable decision record.
How This Skill Works
Capture each decision using the ADR template (Title, Date, Context, Decision, Alternatives, Consequences, Affected Files). Store the ADR in project docs under docs/adr/ or in memory, and link related decisions for cross-reference.
When to Use It
- After choosing a technology, framework, or pattern
- After making an architectural decision
- After deciding NOT to do something (negative decisions are valuable)
- When you realize "we keep coming back to this question"
- When evaluating a major design trade-off or refactor
Quick Start
- Step 1: Capture the decision in ADR format with a short title
- Step 2: Store it in docs/adr/ (or memory) and note affected files
- Step 3: Present the ADR to the user for confirmation before saving (10-20 lines max)
Best Practices
- Use the ADR format with the exact sections (Decision, Context, Alternatives, Consequences, Affected Files)
- Be specific in Context and Decision to avoid ambiguity later
- Document Alternatives Considered and reasons for rejection
- Note positive and negative consequences and trade-offs
- Store ADRs centrally (docs/adr/ or memory) and cross-reference related decisions
Example Use Cases
- ADR for migrating from MySQL to PostgreSQL, including migration path and constraints
- ADR for choosing a web framework (e.g., React vs Vue) and the rationale
- ADR for selecting a caching strategy (Redis vs in-memory) and expected performance
- ADR for monolith vs microservices refactor and the addressing trade-offs
- ADR for enabling a feature-flag approach and rollback plan
Frequently Asked Questions
Add this skill to your agents
