Skip to content
Skills Library
Programming · Analysis

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.

Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

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

  1. When to Use This Skill
  2. 1. A mention is not a caller
  3. 2. A derived fact belongs in the consumer
  4. 3. A registry that gains a second kind breaks every consumer that assumed one
  5. 4. Scripted source edits: anchors, batches and counts
  6. Related
Original SKILL.md headings · 157 lines, 1,300 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.