decision-skill

Use when making architectural or business logic decisions during conversations - adds entry to DECISIONS.md

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill streamlines the creation and maintenance of Architectural Decision Records (ADR) and business logic documentation. By automatically appending structured entries to a DECISIONS.md file, it ensures that the rationale behind technical choices and business rules is preserved, enhancing project transparency and long-term maintainability for development teams.

Use Cases

  • Architectural Decision Records (ADR): Documenting the selection of frameworks, design patterns, or system structures to provide historical context for the team.
  • Business Logic Documentation (BIZ): Recording specific calculation rules, validation logic, or behavioral requirements to ensure consistency across the application.
  • Trade-off Analysis: Capturing the 'Options Considered' and 'Reasoning' when choosing between multiple valid technical approaches during the development process.
  • Post-Debugging Insights: Logging non-obvious behavior requirements discovered during troubleshooting to prevent future regressions.
namedecision-skill
descriptionUse when making architectural or business logic decisions during conversations - adds entry to DECISIONS.md

Decision Documentation Skill

Records architectural (ADR) and business logic (BIZ) decisions to DECISIONS.md.

When to Use

  • Making an architectural choice (framework, pattern, structure)
  • Defining business logic rules (calculations, limits, behavior)
  • Choosing between multiple valid approaches
  • After debugging reveals a non-obvious behavior requirement

Decision Types

Prefix Use For Examples
ADR Architecture Tech stack, patterns, code organization
BIZ Business logic Calculations, rules, validation logic

Workflow

1. Determine Next Number

Read DECISIONS.md and find highest ADR-NNN or BIZ-NNN number:

grep -E "^### (ADR|BIZ)-[0-9]+" DECISIONS.md | tail -1

Use next number in sequence (project uses single sequence for both types).

2. Determine Date Section

Decisions are grouped by date. Check if today's date section exists:

  • If yes: Add under existing date header
  • If no: Create new date section at TOP (after template, before previous entries)

3. Add Decision Entry

Format (add at TOP of decisions, newest first):

## YYYY-MM-DD: {Category}

### {ADR|BIZ}-NNN: {Title}

**Context:** What situation prompted this decision?

**Options considered:** (if applicable)
1. Option A - description
2. Option B - description

**Decision:** What was decided?

**Reasoning:** Why this choice?

4. Commit

git add DECISIONS.md
git commit -m "docs: add {ADR|BIZ}-NNN {short-title}"

Examples

Architecture decision:

### ADR-010: Use Svelte Stores for State

**Context:** Need to share vehicle data between components.

**Decision:** Use Svelte stores (not context or props drilling).

**Reasoning:** Stores are simpler, reactive, and match existing patterns in codebase.

Business logic decision:

### BIZ-012: Round Consumption to 2 Decimal Places

**Context:** Display precision for l/100km values.

**Decision:** Always round to 2 decimal places for display.

**Reasoning:** Matches Excel output and is sufficient precision for legal documents.

Notes

  • Keep entries concise - future you needs quick scanning
  • Always include reasoning - the "why" matters most
  • Link to tech debt if decision creates known limitations
  • Use "Options considered" only when multiple approaches were evaluated