code-derived-facts
/code-derived-facts
Verify code facts by running code, not grepping: is a function really called, is a derived table stale, did a scripted edit write. Use when auditing reachability or batch-editing source.
- Author
- laurigates ↗
- Repository
- claude-plugins ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Verify code facts by running code, not grepping: is a function really called, is a derived table stale, did a scripted edit write. Use when auditing reachability or batch-editing source.
Original author description
Verify code facts by running code, not grepping: is a function really called, is a derived table stale, did a scripted edit write. Use when auditing reachability or batch-editing source.
How it works
- When to Use This Skill
- 1. A mention is not a caller
- 2. A derived fact belongs in the consumer
- 3. A registry that gains a second kind breaks every consumer that assumed one
- 4. Scripted source edits: anchors, batches and counts
- Related
SKILL.md preview
---
name: code-derived-facts
description: "Verify code facts by running code, not grepping: is a function really called, is a derived table stale, did a scripted edit write. Use when auditing reachability or batch-editing source."
allowed-tools: Read, Grep, Glob, Edit, Bash, TodoWrite
created: 2026-11-06
modified: 2026-11-07
reviewed: 2026-11-06
---
# Code-Derived Facts
Four ways a codebase reports a fact that its text supports and its execution
does not: a tool counted as reachable because its name appears in a comment, a
fact derived once with a pattern and then read from a table, a registry whose
new kind silently changes every consumer, and a scripted edit that reports
success without writing. Each produces a clean report over a broken system.
## When to Use This Skill
| Use this skill when... | Use something else when... |
|---|---|
| Deciding whether a script, module, endpoint or flag is still used | Finding unused exports with a dead-code tool → `code-dead-code` |
| Writing a table of "which items need X" from a scan | Errors swallowed by `\|\| true` or empty `catch` → `code-hidden-failures` |
| Adding a second kind of thing to a registry, enum, tag list or wire format | Classifying matches before a bulk rename → `bulk-sweep-classify` |
| Editing many sites in a large source file with a throwaway script | Replacing code by AST shape → `ast-grep-search` |
## 1. A mention is not a caller
A tool nothing invokes does not fail. It sits there, unreachable, with no error
and no red test. **A script is reachable only if something executes it: a
recipe, an import, an invocation. A filename in prose is not reachability**,
and an audit that counts prose certifies exactly the tools it was written to
find. A test suite that never imports a module stays green while the module is
broken.
```python
# WRONG: a comment mentioning the file counts as a caller
refs = sum(1 for m, t in text.items() if m != n and n in t)
# RIGHT: only an import or an actual invocation makes it reachable
refs = sum(
1 for m, t in text.items()
if m != n and (
re.search(rf"^\s*(?:import|from)\s+{re.escape(stem)}\b", t, re.M)
or re.search(rf"import_module\(\s*['\"]{re.escape(stem)}", t)
or re.search(rf"(?:subprocess|run|check_call|Popen)[^\n]*{re.escape(n)}", t)
)
)
```
1. **An orphan is not a defect.** Most are one-shot: a migration already run, a
builder used by hand every few months, a probe kept as evidence. Keep an
`EXPECTED` roster **with a reason per entry** and report only unclassified
orphans. "It was already on the list" is not a reason.
2. **Prove the audit can fire.** Drop a throwaway script into the directory and
confirm the check exits non-zero and names it; remove it and confirm exit 0.
3. **Mount the audit on a recipe or CI step**, not on someone remembering it.
The same shape: dead-code detectors keyed on a symbol that also appears in a
docstring; "is this endpoint used?" answered by grepping the route string,
which hits the API docs; dependency pruning that spares a package named in a
comment; feature-flag cleanup that keeps a flag a migration note mentions.
## 2. A derived fact belongs in the consumer
Computing a fact with an ad-hoc pattern, writing the result into a table, and
consulting the table makes the pattern's blind spot a property of the table.
**A fact derived with a regex is a reading, not a record. Put the derivation in
the code that consumes it, so the consumer refuses when the reading is wrong.**
1. **Derive where the consumer runs.** A resolver that reads the source and
refuses cannot be out of date with it; a committed table can.
2. **Make the guard's pattern looser than, and independent of, the one that
derived the fact.** Its value is catching what the first pattern missed. A
guard written from the same regex cannot fail.
3. **A near-right aggregate is not corroboration.** A total within 10% can sit
on a per-item map that is wrong about the items you act on.
4. **Mutation-test the guard and check which check fired.** A mutation caught by
a different, earlier check proves nothing about the guard.
5. **Ask the question the consumer needs.** "Is it where I put it" passes while
"is something already there" fails.
The same shape: a roster of "files that need X" grepped once and committed; a
coverage or ownership map built by pattern-matching; any `EXPECTED_*` constant
derived from a scan; a test fixture generated by the parser under test.
## 3. A registry that gains a second kind breaks every consumer that assumed one
When a table that has always held one kind of thing starts holding two, every
place that iterated it is now wrong, and most of them do not raise: they
compute something plausible from the wrong set. **Adding a kind to a registry
is not an additive change.** The reads that keep working are more dangerous
than the reads that break, and the worst sit in another file the change did not
touch.
- **Give the filter one home** the moment there are two kinds (`people(tags)`,
not six inline `t not in SETS` copies, all of which go wrong when a third kind
arrives).
- **Name the namespaces explicitly** (`PERSON_TAGS`, `SET_TAGS`, `ALL_TAGS`),
with a comment saying which question each answers.
- **Grep for the old registry's name and every hand-written membership test**,
not for compile errors. In dynamic code, the exceptions are the minority.
- **Run the downstream consumers**, including scripts in other files that the
change "doesn't touch".
A wire format gaining a delimiter is the same event:
- **Grep for the format across the whole tree.** A second consumer re-declares
its own regex rather than importing the first.
- **A consumer that produces empty output must refuse.** A counter that matches
nothing reports zero and passes every check.
- **Move the patterns with the format in the same change**, then re-run each
check's control to confirm it can still refuse.
Length bounds, hand-listed subsets and parallel numbering systems:
[REFERENCE.md](REFERENCE.md#registry-and-pattern-traps).
## 4. Scripted source edits: anchors, batches and counts
A throwaway `s.replace(old, new)` script is the practical way to change many
sites in a large file. Three failure modes cost time and silently drop edits.
1. **An anchor spanning a source line wrap never matches.** Long prose is often
adjacent string literals; the wrap is invisible when reading and real in the
file. `str.replace` then does nothing. Anchor on a fragment that fits on one
source line, `grep -n` it first, and prefer the Edit tool for a handful of
edits: it fails loudly on an absent or non-unique match.
2. **One write at the end makes the batch all-or-nothing.** An `assert` that
raises on substitution #4 discards #1 to #3, and the traceback reads as "the
first one failed". Never `assert` inside a batch that writes at the end;
report `MISS` and continue. **Print `ok` only after the bytes are on disk**:
write first, then report.
3. **`replace()` without a count changes every occurrence.** Pass `count=1`
unless a global rename is intended, print `s.count(old)` first when unsure,
and re-grep the edited region for the words you replaced out.
```python
applied = []
for label, old, new in subs:
if old in s:
s = s.replace(old, new, 1); applied.append(label)
else:
print(" MISS", label)
p.write_text(s) # write first
for label in applied: print(" ok ", label) # then report
```
**The gate**: after any scripted edit, run the program or generator the file
belongs to. Two of the three failures produce syntactically valid code, so
neither the interpreter nor a linter is the gate; the program's own checks are.
## Related
- [REFERENCE.md](REFERENCE.md) — length-bounded patterns, hand-listed subsets,
parallel numbering systems
- `code-dead-code` — tool-driven unused-code detection
- `code-hidden-failures` — swallowed errors and success on zero results
- `bulk-sweep-classify` — which matches to change in a sweep
- `testing-plugin:measurement-controls` — a check that cannot fail has tested
nothing
- `documentation-plugin:docs-claim-hygiene` — readings written into prose
Distilled from rules in the laurigates/comfyui-nodes repository, whose dated
instances are the provenance for each law.
Files in this package (2)
- REFERENCE.md 3 KB
- SKILL.md 8 KB
Versions
The database has no other skills named code-derived-facts.
Database snapshot: 13.11.2026 · package version f982c3dde82e (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100readme-reference
Use when making code, workflow, testing, deployment, or documentation changes in this repository and you need targeted project-specific facts from README files before editing. Read only the relevant section, verify it against code, and repair stale documentation when the task includes documentation. - 100source-trail
Use when work depends on docs, API or library facts the code can't confirm and the answer is worth keeping. Not for facts the repo itself settles. - 91derived-freshness
Use when a generated file must not be older than the source it renders. - 100codebase
Use when performing research on the current codebase — finding where a symbol is defined, discovering all call sites of a function, understanding a type's structure, tracing interface implementations, or answering any question about what the code does right now at the checked-out commit. - 96qa-project-context
Bootstrap or refresh evidenced QA project facts in .agents/qa-project-context.md when onboarding a consuming automation project, facts are missing or stale, or the user asks to configure project context. Do not require this skill for every small edit. - 100find-usage
Find all production code locations where a class, function, or method is defined and used. Use when the user asks where something is defined, instantiated, invoked, or called in production code.