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".