decision-capture

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 session-journal sync at end (Phase 5 of notion-sync)
3. Only HIGH impact items create immediate ADR files

Querying Patine

Before proposing new patterns, query existing decisions:

API-query-database:
  database_id: "[DECISION_PATINE_DB_ID]"
  filter:
    property: "Domain"
    select:
      equals: "[current domain]"

Use results to:

1. Avoid re-proposing rejected alternatives
2. Understand existing constraints
3. Reference past decisions in new proposals

Anti-Patterns

DON'T:

• Require rationale for every micro-decision
• Create ADR files for non-architectural choices
• Capture decisions that are already in code comments
• Ask "why" more than once if human declines

DO:

• Capture at the moment of friction (KO, challenge)
• Accept "we tried this before, it failed" as valid rationale
• Keep entries scannable (1-2 sentences)
• Link to evidence when available (PRs, issues, metrics)

Integration

This skill is invoked by:

• ask.mdc - Gates 1, 2, 3 on KO
• plan.mdc - Gate 4 on option rejection
• push-pr.mdc - Gate 5 on changes requested
• debug - When pattern worth remembering is found

Notion Database Schema

Database: Decision Patine

| Property | Type | Required | |----------|------|----------| | Title | Title | Yes | | Domain | Select | Yes | | Type | Select | Yes | | Decision | Rich Text | Yes | | Rationale | Rich Text | No | | Rejected | Rich Text | No | | Challenged By | Person | No | | Date | Date | Yes | | Impact | Select | Yes | | Gate | Select | No | | Related Task | Relation | No | | ADR File | URL | No |

Invocation

Invoked automatically at Gates on KO, or manually with "use decision-capture skill".