Update Practices

---
name: update-practices
description: Process the practices inbox, evaluate, incorporate into dotforge, and suggest propagation to projects.
---

# Update Practices

3-phase pipeline to keep dotforge up to date with discovered practices.

**Practice sources:**
- Post-session hook (`detect-claude-changes.sh`) → automatic
- Manual capture (`/forge capture`) → user
- For manual web search: research and then use `/forge capture` with the findings

---

## Phase 1: EVALUATE — Process inbox

Read all files in `$DOTFORGE_DIR/practices/inbox/`.

For each practice:

### Acceptance criteria
1. **Is it actionable?** — Can be translated into a concrete change in dotforge
2. **Is it new?** — Does not duplicate something already in `practices/active/`
3. **Is it generalizable?** — Applies to >1 project (not project-specific)
4. **Does it prevent a specific error?** — If yes, annotate `error_type` and error description for tracking in metrics.yml

### Classify
- **Accept** → move to `practices/evaluating/`, note proposed concrete change
- **Reject** → remove from inbox with a note explaining why
- **Defer** → leave in inbox with tag `needs-more-info`

### Priority
1. Security (vulnerabilities, permissions)
2. Breaking changes (APIs that changed)
3. New features that simplify something existing
4. Patterns validated in >1 project
5. Minor optimizations

Show summary:
```
═══ INBOX EVALUATION ═══
{{N}} practices in inbox

✅ ACCEPT: {{title}} → {{proposed change}}
❌ REJECT: {{title}} → {{reason}}
⏸️ DEFER: {{title}} → {{what is missing}}

Proceed with accepted? (yes/no/select)
```

---

## Phase 2: INCORPORATE — Apply changes to dotforge

For each accepted practice in `evaluating/`:

### Determine impact
| Change type | Affected files | Version bump |
|-------------|----------------|--------------|
| New/modified rule | template/rules/, stacks/*/rules/ | minor |
| New/modified hook | template/hooks/, stacks/*/hooks/ | minor |
| Documentation | docs/*.md | patch |
| Modified template | template/*.tmpl | minor |
| Security fix | any | patch |

### Apply
1. Show proposed diff to the user and ask for confirmation
2. Modify the corresponding dotforge files
3. **If the practice warrants a new rule**: generate a `.md` file in `template/rules/` or `stacks/*/rules/` with proper `globs:` (eager) or `paths:` + `alwaysApply: false` (lazy) frontmatter. Only create a rule if the practice is a repeatable constraint (not a one-time fix). Use existing rules as format reference.
4. Move practice from `evaluating/` to `active/` with `incorporated_in:` updated
5. Set frontmatter fields: `effectiveness: monitoring` (or `informational` if no error targeted — informational is excluded from the validation rate metric), `error_type` matching CLAUDE_ERRORS.md types
6. Register in `$DOTFORGE_DIR/practices/metrics.yml`:
   - `error_targeted`: description of the error this practice prevents (null if not error-targeted)
   - `error_type`: syntax | logic | integration | config | security | null
   - `activated`: today's date
   - `status`: monitoring (or informational — for general-knowledge practices, never validated)
   - `recurrence_checks`: 0
   - `recurrence_target`: 5
7. Update `docs/changelog.md`
8. Bump `VERSION` according to type

---

## Phase 3: PROPAGATE — Suggest project updates

1. Read `$DOTFORGE_DIR/registry/projects.yml`
2. For each project, show what changed since its last sync:

```
═══ SUGGESTED PROPAGATION ═══

project-a (last sync: {{date or "never"}})
  → {{N}} rules updated

project-b (last sync: {{date or "never"}})
  → {{N}} rules updated

To propagate: run /forge sync in each project.
```

DO NOT propagate automatically. Inform only.

---

## Phase 4: VERIFY — Recurrence check for active practices

For each entry in `$DOTFORGE_DIR/practices/metrics.yml` where `status: monitoring`:

1. Read `CLAUDE_ERRORS.md` from each project in registry where the practice is applied
2. Check if any error matching `error_type` + `error_targeted` description was logged AFTER the `activated` date
3. Increment `recurrence_checks` by 1, update `last_checked` to today
4. If error recurred: set `recurred: true`, `status: failed`
5. If `recurrence_checks >= recurrence_target` and `recurred: false`: set `status: validated`
6. Update `effectiveness` field in the practice's frontmatter file to match

Report:
```
═══ EFFECTIVENESS CHECK ═══
{{practice title}} — {{status}} ({{recurrence_checks}}/{{recurrence_target}} checks)
  {{if failed: "⚠ Error recurred — practice needs revision"}}
  {{if validated: "✅ No recurrence after {{N}} checks"}}
  {{if monitoring: "🔍 {{remaining}} checks remaining"}}
```

Skip practices with `status: informational` or `status: validated`. Informational practices are general-knowledge captures — they don't target an error, so recurrence is undefined and they never enter the validation rate.

---

## Final report

```
═══ UPDATE REPORT ═══
Date: {{YYYY-MM-DD}}

Evaluated: {{N}} ({{accepted}} accepted, {{rejected}} rejected, {{deferred}} deferred)
Incorporated: {{N}} into dotforge
Propagation suggested: {{N}} projects

── EFFECTIVENESS ──
Monitoring: {{N}} practices
Validated: {{N}} (no recurrence after {{target}} checks)
Failed: {{N}} (need revision)

VERSION: {{old}} → {{new}}
```