Decision Capture
Productivitydecision-captureDecision Capture is an Agent Skill for productivity published in the WellApp-ai/Well repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Capture patine (decision wisdom) at Gates when KO or challenge occurs
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/WellApp-ai/Well/blob/HEAD/cursor-rules/skills/decision-capture/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/decision-capture, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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:
- Get next ADR number:
ls docs/decisions/ | wc -l - Create file:
/docs/decisions/NNN-[slug].md - 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:
- Collect Kaizen/Hansei entries in memory during session
- Aggregate in session-journal sync at end (Phase 5 of notion-sync)
- 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:
- Avoid re-proposing rejected alternatives
- Understand existing constraints
- 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 KOplan.mdc- Gate 4 on option rejectionpush-pr.mdc- Gate 5 on changes requesteddebug- 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".