decision-documentation
Scannednpx machina-cli add skill a5c-ai/babysitter/decision-documentation --openclawDecision Documentation
Overview
Document significant architectural and technical decisions as Architecture Decision Records (ADRs). Can be invoked at any point during the RPI workflow.
When to Use
- Making a significant architectural choice
- Choosing between competing approaches
- Documenting a decision for future reference
- Recording rationale that would otherwise be lost
ADR Format
- Title: Clear description of the decision
- Status: Proposed, Accepted, Deprecated, Superseded
- Context: Why this decision is needed
- Options: Alternatives considered with pros/cons
- Decision: The chosen option with rationale
- Consequences: Expected positive and negative outcomes
Output
ADRs are written to docs/decisions/ with sequential numbering (e.g., 0001-use-typescript.md).
Tool Use
Invoke via babysitter process: methodologies/rpikit/rpikit-decision
Source
git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/methodologies/rpikit/skills/decision-documentation/SKILL.mdView on GitHub Overview
This skill helps teams capture significant architectural and technical decisions as Architecture Decision Records (ADRs). It ensures decisions are recorded with context, options, consequences, and a clear rationale, helping future maintenance and knowledge transfer within the RPI workflow.
How This Skill Works
When invoked, it creates an ADR file following the ADR format (Title, Status, Context, Options, Decision, Consequences) and saves it under docs/decisions/ with a sequential filename like 0001-.... The ADR can be created at any point in the RPI workflow and referenced in ongoing work.
When to Use It
- Making a significant architectural choice
- Choosing between competing approaches
- Documenting a decision for future reference
- Recording rationale that would otherwise be lost
- Recording decisions that affect multiple components or teams within the RPI workflow
Quick Start
- Step 1: Trigger ADR creation via the babysitter process: methodologies/rpikit/rpikit-decision
- Step 2: Fill Title, Context, Options, Decision, and Consequences
- Step 3: Save to docs/decisions/ with the next sequential number and reference in related work
Best Practices
- Write ADRs with a clear Title, Status, Context, Options, Decision, and Consequences.
- Keep ADRs focused on a single decision.
- Document alternatives and rationale clearly in Options.
- Number ADRs sequentially (0001-...).
- Update or supersede ADRs as decisions evolve, with status changes.
Example Use Cases
- 0001-use-typescript.md: ADR to adopt TypeScript for core services (Context, Options, Decision, Consequences).
- 0002-graphql-vs-rest.md: ADR evaluating GraphQL vs REST for API surface.
- 0003-cloud-provider.md: ADR selecting AWS as cloud provider due to mature services.
- 0004-database-strategy.md: ADR choosing PostgreSQL with JSONB for flexibility.
- 0005-caching-strategy.md: ADR selecting Redis as primary cache with TTL policies.
