Grudge

Grudge — the Book of Grudges (#271)

> Named for the dwarven Dammaz Kron: every wrong is written down and never > forgotten until it is settled. A fixed bug becomes a grudge the toolchain > holds against the files that caused it — and refuses to let happen again.

Stock Claude Code has no memory across sessions, so the same class of bug re-ships. The grudgebook closes the loop: write-on-resolution + read-on-preflight.

Where grudges live (read this first)

The grudgebook is machine-local and per-repo, NEVER inside a git tree:

$CRUCIBLE_GRUDGE_DIR  (or ~/.claude/crucible/grudge)
  //grudges/.md

Grudges carry private file paths + repro detail and crucible is PUBLIC, so the live store must stay outside any repo (mirrors the calibration ledger central store, PR #326). scripts/grudge_append.py refuses to write into the current repo's tree. The committed .crucible/grudge/grudges/*.md are synthetic fixtures only. Isolation is by repo_root (git toplevel realpath), so two checkouts that share a basename never bleed into each other.

Resolving the helpers (cwd-independent)

A gating skill runs with an arbitrary cwd, so locate the scripts by absolute path from the plugin root (same convention as shared/ledger-append.md):

# plugin layout is invariant: /skills// and /scripts/
plugin_root="$(realpath "/../..")"
query="$plugin_root/scripts/grudge_query.py"
append="$plugin_root/scripts/grudge_append.py"
# If unresolved: emit a one-line stderr warning and SKIP. The grudgebook is
# advisory; a missing query/record must NEVER block or fail the host skill.

Read mode (pre-flight — "what grudges do we hold here?")

Before writing/reviewing code, pass the in-scope files (absolute, ./-prefixed, or repo-relative — all normalized) to the query helper and inject any output into your working context as a hard constraint:

python3 "$query" path/to/file1 path/to/file2 [--with-signatures] [--limit N]

• Path match is always on. Add --with-signatures when you already have file

contents in hand (it greps anti_pattern_signature regexes against file bodies).

• Non-empty output = grudges held against these files. Treat each ☠ line as

DO NOT REPEAT — do not re-introduce that bug.

• Maintenance: --stats (how many grudges held / recently written — spot

starvation) and --cull (strike settled grudges whose files are all gone).

• A stderr line grudge: scanned=… matched=… skipped_stale=… always prints so a

silent/empty grudgebook is visible.

Write mode (record a grudge — on bug resolution / fix(*) PR)

When a bug is confirmed fixed, record it (best-effort; a failed record logs to stderr and never fails the host skill):

python3 "$append" \
  --symptom "one-line observable failure" \
  --root-cause "one-line underlying cause" \
  --files "src/a.py,src/b.py" \
  --signature "optional regex or literal snippet that fingerprints the bug" \
  --commit "" \
  --repro "minimal repro steps" \
  --why "why this kept happening"

Grudge schema

---
schema: 1
hash: 
repo:             # cosmetic dir name
repo_root:    # isolation key; reads filter on this
fixed_in_commit:       # recorded, NOT part of the key
symptom:          # dedupe discriminator when no signature
root_cause: 
files_touched: ["repo/rel/path", ...]
anti_pattern_signature: ""   # optional
date_fixed: YYYY-MM-DD
---
## Repro

## Why this kept happening

Dedupe: key excludes fixed_in_commit (one bug can be fixed in many commits); discriminator = anti_pattern_signature when non-empty else symptom. Same key → overwrite (last write wins). A grudge with neither files nor a discriminator is rejected.

Consumers (where the wiring lives)

• Pre-flight (read): build (Phase 2, post-design/pre-implementation),

quality-gate (round-1 dispatch), debugging (opening phase).

• Write: debugging (resolution phase), merge-pr (on fix(*) PRs).

Non-goals (v1)

No semantic search (glob + regex only); no cross-user shared grudgebook (sanitized community grudges — v1.1 candidate); no settings.json hook.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: raddue
• Source: raddue/crucible
• License: MIT

Install and usage instructions live in the source repository linked above.