Lore Guard
Read ${CLAUDE_PLUGIN_ROOT}/reference/lore-spec.md first — the entry-meta format and the feedback-log format come from there.
lore-consult reads lore before work starts. This skill is the other bookend: it re-checks the result of the work, because rules that were surfaced can still get lost during implementation, and rules nobody thought to surface can turn out to apply. Without this pass, nothing stands between a diff that quietly breaks a recorded business rule and the commit that ships it.
When to use
After implementing a change and before committing or opening a PR, in a repo that has docs/lore/. Also on an explicit ask like "does this change break any of our rules?". If there is no docs/lore/, say so briefly and move on — there is nothing to guard against.
Procedure
- Collect the changed files. Take the union of staged and unstaged changes (
git diff --name-only HEAD, plus untracked files that belong to the change). If the user points at a specific diff or branch, use that instead.
- Reverse-lookup by
code: link. Grep every `code:` reference across docs/lore/ and keep the entries whose path intersects the changed files. Match by prefix too — an entry pointing at src/payments/ covers any changed file under it, and an entry pointing at a file covers that file's changes.
- Widen by area. Map the changed files to areas via the
docs/lore/README.md index, and scan those areas' pitfalls.md / business-rules.md headings for entries that clearly bear on the change even though their code: link points elsewhere. The code: match is precise but incomplete; this step catches the rest. Skip non-active entries unless one is directly relevant.
- Judge each matched entry against the actual diff. Read the diff hunks, not just the filenames, and classify: violated (the change conflicts with the entry), respected (the change complies), or not applicable. When an entry contradicts the current code but the diff isn't what broke it, don't call it a violation — flag it as possibly stale and point at
lore-maintain.
- Naming check. Resolve the glossary per lore-spec — a root
CONTEXT.md / CONTEXT-MAP.md when present, otherwise docs/lore/glossary.md (or an area's terms.md). If one exists, scan the diff's added lines for identifiers and user-facing strings that hit a term's banned-name list (not: in lore's format, _Avoid_: in CONTEXT.md). Judge semantics before flagging: client naming an HTTP client is fine; client naming the paying party when the glossary says Customer is a violation. Read the hunk, not just the match. Report a hit like any other violation — the term's heading, the banned name the diff introduced, and the canonical name to use instead.
- Report. Violations first: the entry heading, its
code: link, what in the diff conflicts, and the direction a fix would take. You never edit code yourself — fixing is the caller's job. When nothing matches, still say so in one line ("lore-guard: N entries checked, no conflicts"), so the user knows the pass actually ran.
- Feedback log (best-effort). Per lore-spec: append a
surfaced event for each entry you judged (glossary terms keyed glossary.md#<Term>, or CONTEXT.md#<Term> when the external glossary is canonical), then reconcile — heeded when a violation was flagged and the user fixed it, redundant when the change already respected the entry, ignored when the user dismissed the flag. Never let logging block or delay the report.
Guardrail
Read-only, both directions: never edit the code under review, and never edit lore. A violation is a report, not an auto-fix. Relevance over completeness — judging five entries that actually touch the diff beats listing fifty that don't.
1---2name: lore-guard3description: Lore Guard4---56# Lore Guard78Read `${CLAUDE_PLUGIN_ROOT}/reference/lore-spec.md` first — the entry-meta format and the feedback-log format come from there.910`lore-consult` reads lore *before* work starts. This skill is the other bookend: it re-checks the *result* of the work, because rules that were surfaced can still get lost during implementation, and rules nobody thought to surface can turn out to apply. Without this pass, nothing stands between a diff that quietly breaks a recorded business rule and the commit that ships it.1112## When to use1314After implementing a change and before committing or opening a PR, in a repo that has `docs/lore/`. Also on an explicit ask like "does this change break any of our rules?". If there is no `docs/lore/`, say so briefly and move on — there is nothing to guard against.1516## Procedure17181. **Collect the changed files.** Take the union of staged and unstaged changes (`git diff --name-only HEAD`, plus untracked files that belong to the change). If the user points at a specific diff or branch, use that instead.192. **Reverse-lookup by `code:` link.** Grep every `` `code:` `` reference across `docs/lore/` and keep the entries whose path intersects the changed files. Match by prefix too — an entry pointing at `src/payments/` covers any changed file under it, and an entry pointing at a file covers that file's changes.203. **Widen by area.** Map the changed files to areas via the `docs/lore/README.md` index, and scan those areas' `pitfalls.md` / `business-rules.md` headings for entries that clearly bear on the change even though their `code:` link points elsewhere. The `code:` match is precise but incomplete; this step catches the rest. Skip non-`active` entries unless one is directly relevant.214. **Judge each matched entry against the actual diff.** Read the diff hunks, not just the filenames, and classify: **violated** (the change conflicts with the entry), **respected** (the change complies), or **not applicable**. When an entry contradicts the current code but the diff isn't what broke it, don't call it a violation — flag it as possibly stale and point at `lore-maintain`.225. **Naming check.** Resolve the glossary per lore-spec — a root `CONTEXT.md` / `CONTEXT-MAP.md` when present, otherwise `docs/lore/glossary.md` (or an area's `terms.md`). If one exists, scan the diff's added lines for identifiers and user-facing strings that hit a term's banned-name list (`not:` in lore's format, `_Avoid_:` in `CONTEXT.md`). Judge semantics before flagging: `client` naming an HTTP client is fine; `client` naming the paying party when the glossary says `Customer` is a violation. Read the hunk, not just the match. Report a hit like any other violation — the term's heading, the banned name the diff introduced, and the canonical name to use instead.236. **Report.** Violations first: the entry heading, its `code:` link, what in the diff conflicts, and the direction a fix would take. You never edit code yourself — fixing is the caller's job. When nothing matches, still say so in one line ("lore-guard: N entries checked, no conflicts"), so the user knows the pass actually ran.247. **Feedback log (best-effort).** Per lore-spec: append a `surfaced` event for each entry you judged (glossary terms keyed `glossary.md#<Term>`, or `CONTEXT.md#<Term>` when the external glossary is canonical), then reconcile — `heeded` when a violation was flagged and the user fixed it, `redundant` when the change already respected the entry, `ignored` when the user dismissed the flag. Never let logging block or delay the report.2526## Guardrail2728Read-only, both directions: never edit the code under review, and never edit lore. A violation is a report, not an auto-fix. Relevance over completeness — judging five entries that actually touch the diff beats listing fifty that don't.
mukiwu