capture-practice

Capture Practice

Register an insight, pattern, or lesson learned in the dotforge inbox.

Input routing

If $ARGUMENTS is empty → auto-detect mode (Step 0). If $ARGUMENTS has content → skip to Step 1.

---

Step 0: Auto-detect (only when $ARGUMENTS is empty)

Analyze the recent conversation to identify the most generalizable insight from this session.

Detection signals (in priority order)

1. Workaround discovered — the obvious approach failed and an alternative was used
2. Multi-attempt bug — a fix required more than one attempt or root cause was non-obvious
3. Architectural decision with trade-offs — two+ alternatives were considered, one chosen with reasoning
4. Non-obvious tool/API/flag behavior — a parameter, edge case, or behavior was surprising
5. Missing rule — the session revealed a gap in .claude/rules/ or CLAUDE.md that would have prevented the problem

Extraction rules

• Extract the single most generalizable insight — not session notes, not a summary of everything done
• Formulate it as a reusable principle: "When X, do Y because Z" or "Never do X — use Y instead"
• Keep it to 1-2 sentences max
• Ignore: trivial tasks, first-attempt successes, routine edits

If no signal is present

Respond: "No generalizable insight detected in this session. If you have something specific in mind, run /cap \"description\"." Stop — do not create a file.

Propose and confirm

Show the proposed insight and ask for confirmation before proceeding:

Proposed practice:
"{{one-line insight}}"

Tags: {{inferred tags}}
Project: {{current project name}}

Save this? [Y/n/edit]

• If Y or user confirms → continue to Step 1 with the proposed text as $ARGUMENTS
• If n → stop, no file created
• If edit or user rewrites → use the rewritten text as $ARGUMENTS, continue to Step 1

---

Step 1: Parse the insight

From $ARGUMENTS (provided or confirmed from Step 0), extract:

• What: the practice or pattern
• Why: evidence or context (current project, error that motivated it)
• Impact: which dotforge files could change
• Tags: categorization (hooks, rules, prompting, security, stack-specific, etc.)

Step 2: Validate duplicates

Before creating, check for existing similar practices:

1. Search $DOTFORGE_DIR/practices/active/ by title or similar tags
2. Search $DOTFORGE_DIR/practices/inbox/ by similar title
3. If duplicate found → inform the user and ask: update existing or create new?

Step 3: Generate file

Create file in $DOTFORGE_DIR/practices/inbox/ with format:

---
id: practice-{{YYYY-MM-DD}}-{{slug}}
title: {{short title}}
source: "own experience"
source_type: experience
discovered: {{YYYY-MM-DD}}
status: inbox
tags: [{{tags}}]
tested_in: {{current project or null}}
incorporated_in: []
replaced_by: null
---

## Description
{{what the practice states}}

## Evidence
{{why it works, discovery context}}

## Impact on dotforge
{{which files would need to change}}

## Decision
Pending

File name: {{YYYY-MM-DD}}-{{slug}}.md

Step 4: Confirm

Show:

Practice captured: {{title}}
File: practices/inbox/{{file}}
Tags: {{tags}}

Next step: /forge update evaluates pending practices from inbox.