decision-capture_skill

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