# Grudge

> The Book of Grudges — cross-session bug graveyard. Every fixed bug is recorded as a structured "grudge"; before touching code, skills query the grudgebook for the files in scope and surface past regressions as forced "DO NOT REPEAT" context. Read mode (pre-flight) and write mode (on bug resolution / fix(*) PR). Machine-local, per-repo, never committed. Triggers on /grudge, "check grudges", "recor…

- **Type:** Skill
- **Install:** `agentstack add skill-raddue-crucible-grudge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [raddue](https://agentstack.voostack.com/s/raddue)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [raddue](https://github.com/raddue)
- **Source:** https://github.com/raddue/crucible/tree/main/skills/grudge

## Install

```sh
agentstack add skill-raddue-crucible-grudge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```markdown
---
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](https://github.com/raddue)
- **Source:** [raddue/crucible](https://github.com/raddue/crucible)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-raddue-crucible-grudge
- Seller: https://agentstack.voostack.com/s/raddue
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.