# Decision Engine

> Architecture Decision Records (ADR) management. Creates, tracks, and queries decisions so the AI agent understands WHY choices were made, not just WHAT was chosen.

- Skill: `kok-o/decision-engine` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kok-o/decision-engine`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kok-o/decision-engine/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kok-o (https://skillmd.com/u/kok-o)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kok-o/decision-engine

---


# decision-engine

## Overview

Architecture Decision Record (ADR) system following Michael Nygard format. Captures context, options considered, tradeoffs, and consequences to prevent architectural regression and knowledge loss across AI sessions.

## When to Use

Activate when choosing or switching database engines, authentication strategies, state libraries, or significant architectural patterns.

## Rules & Patterns

You manage **Architecture Decision Records** (ADRs).

## Why Decisions Matter

Without ADRs, the AI agent sees:

- "Database: PostgreSQL" — but doesn't know WHY
- "Auth: JWT" — but doesn't know what alternatives were considered
- "Framework: Next.js" — but doesn't know the tradeoffs

With ADRs, the agent understands the reasoning and won't accidentally contradict prior decisions.

## Commands

### Create a Decision

When an architectural choice is made during any pipeline stage:

1. Auto-increment the decision number
2. Use the template from `generators/templates/DECISION.md`
3. Save to `docs/decisions/NNNN-decision-name.md`
4. Update the Project Graph if the decision affects modules

**Naming convention:** `docs/decisions/0001-use-postgresql.md`

### Query Decisions

Before making changes that touch architecture:

1. Check `docs/decisions/` for related decisions
2. If a decision exists, follow it
3. If a decision needs to change, create a new ADR that **supersedes** the old one

### Decision Lifecycle

```
proposed → accepted → [deprecated | superseded]
```

- **proposed**: Under discussion, not yet committed
- **accepted**: The team agreed, this is the standard
- **deprecated**: No longer relevant (project evolved)
- **superseded**: Replaced by a newer decision (link to it)

## Auto-Detection

The Decision Engine should suggest creating an ADR when it detects:

- A new database/ORM is introduced
- A new framework is added
- Authentication strategy changes
- API versioning approach is chosen
- Deployment strategy is decided
- A significant library is added (state management, testing framework, etc.)


## Code Examples

See `EXAMPLES.md` for detailed code examples.

## Validation Checklist

What to verify during the review phase before completing the task.

## Common Mistakes

Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.

## Integration Notes

How this skill interacts with other skills.