home / skills / velcrafting / codex-skills / decision-capture

decision-capture skill

safe

This skill captures non-trivial decisions as proposed entries for a repository's decision log to combat drift and enable ratification.

npx playbooks add skill velcrafting/codex-skills --skill decision-capture

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.2 KB

---
name: decision-capture
description: Capture non-trivial decisions as a proposed entry for a repo's decision log (e.g., DECISIONS.md). Use when work involves meaningful tradeoffs.
---
# Decision Capture

## Goal
Prevent silent drift by turning meaningful choices into explicit, ratifiable decisions.

## Non-negotiables
- Read-only. Do not edit files automatically.
- Do not claim a decision is accepted. Only propose.
- Keep it concrete and short.

## When to use
- Architecture choices, domain boundaries, data model changes, risk invariant changes, migrations, irreversible moves.
- Any time the plan depends on a major assumption or includes “choose one of X”.

## Output (follow exactly)

# Proposed Decision

## Title
<Short, specific title>

## Context
<What problem forced this choice?>

## Decision
<What we will do>

## Alternatives considered
- A1: <alternative> (why not)
- A2: <alternative> (why not)

## Consequences
- Positive:
- Negative:
- Risks:

## Enforcement / follow-through
- Boundaries:
- Validation:
- Docs impacted:

## Review
- Needs ratification: <yes/no>
- Review after: <YYYY-MM-DD or "n/a">

## Append targets
- Decision log file: <e.g., DECISIONS.md path>
- Review queue file (if any): <e.g., REVIEW_QUEUE.md or "n/a">

Overview

This skill captures non-trivial engineering and product decisions as a proposed entry for a repository decision log. It helps teams make assumptions and tradeoffs explicit, short, and ratifiable without making automatic edits. Use it to prevent silent drift and preserve rationale for future review.

How this skill works

The skill inspects your context and prompts you to produce a concise, structured decision proposal that follows a fixed template. It operates read-only: it generates the proposed entry text for a human to review and add to the decision log. The output is intentionally concrete, short, and framed to support later ratification and follow-through.

When to use it

When a design or architecture choice involves meaningful tradeoffs or irreversible moves
For changes to domain boundaries, data models, or risk invariants
When a migration or deployment strategy has major assumptions
Whenever the plan requires choosing one option from several plausible alternatives
Before merging work that depends on a major assumption to ensure visibility

Best practices

Keep titles short and specific to make decisions scannable
State the context clearly: what problem or constraint forced the choice
List only meaningful alternatives and why they were rejected
Keep consequences concrete: separate positives, negatives, and risks
Mark whether the proposal needs ratification and a review date

Example use cases

Choosing between two database schemas that are hard to migrate between
Proposing a domain split that affects multiple services and teams
Deciding to adopt or defer a third-party dependency with operational costs
Documenting a rollout strategy that cannot be easily reversed
Recording a security or compliance decision that changes risk profiles

FAQ

Will this skill modify the repository automatically?

No. It generates a read-only proposed entry for a human to review and add to the decision log.

Does the skill mark a decision as accepted?

No. It only proposes a decision; acceptance or ratification must be recorded by the team.

How long should proposals be?

Keep proposals short and concrete—enough to capture context, decision, alternatives, consequences, and follow-through.