/decision-capture

name: decision-capture
description: Capture patine (decision wisdom) at Gates when KO or challenge occurs

Decision Capture Skill

Lightweight skill for capturing the "patine" - the accumulated wisdom of why decisions were made and alternatives rejected. Triggered at Gates when human provides KO or challenges a proposal.

When to Use

• At any Gate when human provides KO
• When human challenges or rejects a proposal
• When debug skill finds a pattern worth remembering
• When significant technical decision is made

Trigger Conditions

| Trigger | Context | Type | |---------|---------|------| | Gate 1 KO | Wireframe rejected | Decision | | Gate 2 KO | Scope option rejected | Decision | | Gate 3 KO/BLOCK | Phasing challenged | Decision | | Gate 4 KO | Technical approach rejected | Decision | | Gate 5 Changes | PR review feedback | Decision | | Debug Pattern | Recurring issue found | Kaizen | | DIG 3+ times | Same wireframe refined repeatedly | Kaizen | | Same error fixed 2+ times | Fix pattern emerged | Kaizen | | User corrects assumption | AI was wrong about something | Hansei | | Takt warning exceeded | Phase took longer than target | Hansei | | Jidoka Tier 2/3 | Escalation to human required | Hansei |

Phase 1: Detect Decision Type

Categorize the decision:

| Type | Signal | Example | |------|--------|---------| | Technical | Code, architecture, library | "Don't use GraphQL subscriptions" | | UX | Interaction, visual, flow | "Sidebar navigation, not top nav" | | Process | Workflow, phasing, priority | "Ship auth before tables" |

Phase 2: Prompt for Rationale

Ask for brief rationale (keep it light):

I'll note this decision for future reference.

**In one sentence, why this decision?**

Examples:
- "We tried X in 2024, broke production"
- "Users missed this in testing"
- "Conflicts with our caching strategy"

(Press Enter to skip if you prefer not to explain)

**If human declines:** Record decision without rationale (still valuable).

Phase 3: Attribute

Capture metadata:

| Field | Source | |-------|--------| | Who | Current user (from context) | | When | Current date | | Domain | From branch name or changed files | | Gate | Which Gate triggered capture | | Related Task | Notion task ID if available |

Phase 4: Store

Layer 1: Notion (Default - Always)

Use Notion MCP to create record:

API-create-page:
  parent: { database_id: "[DECISION_PATINE_DB_ID]" }
  properties:
    Title: { title: [{ text: { content: "[Decision summary]" }}]}
    Domain: { select: { name: "[domain]" }}
    Type: { select: { name: "[Technical/UX/Process]" }}
    Decision: { rich_text: [{ text: { content: "[What we decided]" }}]}
    Rationale: { rich_text: [{ text: { content: "[Why]" }}]}
    Rejected: { rich_text: [{ text: { content: "[What we didn't do and why]" }}]}
    Impact: { select: { name: "[Low/Medium/High]" }}
    Gate: { select: { name: "[Gate 1/2/3/4/5/Debug]" }}

Layer 2: ADR File (If High Impact)

If Impact = High or Type = Technical with cross-domain effect:

1. Get next ADR number: `ls docs/decisions/ | wc -l` 2. Create file: `/docs/decisions/NNN-[slug].md` 3. Use ADR template

**ADR Template:**

# ADR-[NNN]: [Title]

**Date**: [YYYY-MM-DD]
**Status**: Accepted
**Domain**: [domain]
**Captured at**: Gate [N]

## Context

[1-2 sentences: What problem were we solving?]

## Decision

[What we chose to do]

## Rationale

[Why this approach - the positive case]

## Rejected Alternatives

### [Alternative Name]
**Why not**: [Reason]

## Consequences

- [Trade-off 1]
- [Trade-off 2]

## References

- Notion: [link to Decision Patine record]
- Task: [link to related task if applicable]

Layer 3: Inline Comment (If Micro/Code-Specific)

For small code-level decisions during implementation:

// ADR: [Brief decision]. [Why not alternative]. —@[initials] [YYYY-MM]

Example:

// ADR: No useMemo here - profiling showed <1ms gain, adds complexity. —@mc 2026-01

Phase 5: Confirm

Output confirmation:

**Noted:** [Decision summary]

Stored in Decision Patine database.
[If ADR created: Created ADR-[NNN] in /docs/decisions/]

Continuing with workflow...

---

Kaizen/Hansei Capture (NEW)

Automatic learning capture without user prompts. These triggers capture patterns and reflections silently.

Automatic Triggers

These captures happen automatically without prompting user:

**Kaizen (pattern emerged):**

• Wireframe DIG'd 3+ times → Capture the pattern that emerged
• Same error fixed 2+ times → Capture the fix pattern
• Repeated code pattern → Capture abstraction opportunity

**Hansei (reflection):**

• User corrects AI assumption → Capture what was wrong
• Phase exceeded takt warning → Capture why it took longer
• Jidoka escalation → Capture what blocked progress

Kaizen Format

Type: KAIZEN
Source: [Phase] [Loop/Commit]
Learning: "[What pattern emerged]"
Category: [UX_PATTERN | TECHNICAL | PROCESS]
Impact: LOW | MEDIUM | HIGH

**Example:**

Type: KAIZEN
Source: DIVERGE Loop 3
Learning: "Invite modals benefit from email preview side panel"
Category: UX_PATTERN
Impact: MEDIUM

Hansei Format

Type: HANSEI
Source: [Phase] [Loop/Commit]
Learning: "[What we learned from the mistake/delay]"
Category: [ASSUMPTION | COMPLEXITY | PROCESS]
Impact: LOW | MEDIUM | HIGH

**Example:**

Type: HANSEI
Source: CONVERGE
Learning: "Original scope too ambitious - exceeded 40min takt warning"
Category: COMPLEXITY
Impact: LOW

Silent Capture Rules

• Do NOT prompt user for rationale on Kaizen/Hansei triggers
• Capture automatically based on observed patterns
• Include in session-journal sync at end of session
• Only HIGH impact Kaizen/Hansei create immediate ADR files

Session Aggregation

Instead of immediately creating Notion entries for each: 1. Collect Kaizen/Hansei entries in memory during session 2. Aggregate in sessi