audit-coupled-constant
Audit every site of a constant whose value is duplicated across multiple call sites (retry budgets, timeouts, page sizes, magic numbers, feature flags). The author-maintained `SEE ALSO` trail is documentation, not enforcement — one missed site means the trail lies. Trigger on /au
Install
npx skills add https://github.com/allemaar/open-skills/tree/main/skills/audit-coupled-constant
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
git clone https://github.com/allemaar/open-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allemaar/open-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
/audit-coupled-constant
Before declaring an edit to a coupled constant complete, grep the constant's value globally to verify every site moved together. The author-maintained SEE ALSO trail is a maintenance contract, not enforcement — when one site is missed, the trail silently lies in the other sites.
Origin. This skill emerged from a cold-review finding. A 60s retry budget was raised to 180s across 3 of 4 call sites; the 4th (
packages/<pkg>/src/flows/rename.ts:297) was missed because the SEE ALSO comments in the 3 known sites never mentioned it. Two independent cold reviewers caught it via global grep; the original diagnosis trusted the SEE ALSO trail. The lesson generalizes far beyond retry budgets.
Boundary
Use audit-coupled-constant when you are about to declare done on an edit that touches a constant whose value is duplicated across multiple files, OR whose comments name other files via "SEE ALSO" / "keep in sync" / "matches" / "mirrors" cross-references. Common shapes:
- Retry / timeout budgets (
240 × 250ms,60_000,60s) - Pagination page sizes / query limits (
PAGE_SIZE = 25) - Feature-flag strings or keys
- Magic numbers reflecting external invariants (max upload size, max URL length, schema version)
- Shared regex patterns or validation thresholds
Do NOT use for constants that are truly local to one file, for purely-imported constants where only the import site moved (the named symbol is the single source), or for constants enforced by the type system (e.g., a TypeScript as const literal imported everywhere — the compiler is your audit).
Authority
An audit request authorizes inspection and a chat report, not code, comment or artifact writes. In audit-only mode, Steps 3–4 identify proposed repairs and the report records them as pending. Apply repairs or save a report only where current authorization already covers the exact effects and scope; reuse that authorization without another prompt. Do not claim an audit is a completed repair.
Step 1 — Identify the constant + its shapes
A coupled constant appears in code under multiple shapes. List every shape you might find before grepping:
- Raw value in code:
240,60_000,0.5,"warn" - Named symbol (if extracted):
RETRY_BUDGET_MS,MAX_PAGE_SIZE - Value-as-comment in documentation:
// 60s budget,/* 240 × 250ms */ - Unit suffix in documentation:
60s,60000ms,1min - Composite expressions that reduce to the value:
60 * 1000,1000 * 60 * 60 - String tokens the value participates in: log lines, error messages, JSON fixtures, test names
Write the list of shapes down before grepping. Missing a shape is the most common cause of a missed site.
Step 2 — Grep each shape across the relevant scope
Run a separate grep for each shape. Use Grep / ripgrep, not find or recursive Read. Examples:
# Choose the actual justified scope; these rg examples do not imply a type filter.
rg -n '\b240\b' <scope>
rg -n -i -F '60s' <scope>
rg -n '240\s*\*\s*250' <scope>
rg -n -F 'RETRY_BUDGET_MS' <scope>
For every shape, record the actual command, searched scope, exit status, hits and any failed/unrun search. An unavailable or unrun search remains a coverage gap; do not declare the audit complete. Explain any file-type exclusions, including docs/fixtures/scripts, against the actual affected invariant.
Set the scope to the package or repo level — coupled constants often span src + tests + scripts. For monorepos, audit each affected package.
Step 3 — Reconcile the hits
Group hits into three categories:
- Moved together — site already updated to the new value as part of your edit. ✓ No action.
- Missed site — site still holds the old value but should move. Update + verify the SEE ALSO chain mentions this site after the update.
- Intentionally different — site holds a different value by design (e.g., test budget intentionally wider than prod, or development tier intentionally lower). Document the intent at the site itself with a comment like
// Intentionally different from registry-reset.ts: tests need 3× the budget for singleFork load.This prevents the next auditor from misclassifying it.
If you cannot tell which category a site belongs in, halt the edit and ask the author or git blame the comment that introduced the value.
Step 4 — Repair the SEE ALSO trail
Apply this step only for authorized repairs; otherwise report the proposed trail changes.
For any newly-found coupled site, add bidirectional SEE ALSO comments so the next auditor doesn't have to re-discover the relationship:
// SEE ALSO: <other-file-1>.ts <function> — keep budgets in sync (180s).
// SEE ALSO: <other-file-2>.ts <function> — keep budgets in sync (180s).
Critically: also UPDATE the SEE ALSO comments in the EXISTING sites to mention the newly-found site. The trail must be bidirectional, or the next person to touch any one site won't know to look at the new one.
Step 5 — Emit the audit report
Brief, structured. One section per scope swept:
audit-coupled-constant report
constant: <name or value>
shapes searched: 240, 60_000, 60s, RETRY_BUDGET_MS
scope: packages/<pkg>
sites found: 4
src/flows/registry-reset.ts:90 moved together ✓
src/scaffold/delete.ts:42 moved together ✓
tests/_helpers/fs-retry.ts:47 moved together ✓
src/flows/rename.ts:297 MISSED — update + add SEE ALSO trail
intentionally-different sites: 0
SEE ALSO trail updated: no (audit-only; propose adding rename.ts to the 3 existing sites)
Rules
- MUST list every shape the constant can appear in (raw value, named symbol, unit-suffixed comment, composite expression, embedded in strings) before grepping.
- MUST run a separate grep for each shape — one grep per shape, not a single broad grep.
- MUST classify each hit into moved-together / missed / intentionally-different. Halt the edit if you can't classify confidently.
- For authorized repairs, MUST update SEE ALSO comments in the existing sites when you find a new site; the trail must be bidirectional. Audit-only mode reports the missing links without changing them.
- MUST NOT trust SEE ALSO comments as enforcement. They are documentation that decays.
- MUST NOT declare an edit done before the audit report shows all sites moved (or are intentionally-different with explicit documentation).
- SHOULD pair with
/cold-reviewfor high-stakes coupled-constant edits (retry budgets that ship to users, schema versions, feature flags wired into rollouts).
Anti-patterns
- "I updated the SEE ALSO sites — done." The SEE ALSO trail's set of named sites may be a subset of all coupled sites. Grep first; trust the trail second.
- Trusting word-boundary grep for short numbers.
240matches1240,2403, etc. without\\b. Always use word-boundary for digit-only constants under 1000. - Skipping the unit-suffixed comment shape. Many sites carry the value as a comment (
// 60s budget) even when the code uses a named symbol. Comments don't move with code refactors and are the silent-drift source. - Treating intentionally-different as "moved together — skip." If the site is intentionally different, the comment at the site must say so. Otherwise the next auditor will flag it as drift and the cycle repeats.
- Auditing only your own edit's scope. The constant may appear in a test fixture, a doc snippet, a script, or a docstring inside a sibling package. Audit the whole repo unless you can prove a tighter scope.
- Adding SEE ALSO to the new site without updating the old sites. Trail must be bidirectional. One-way SEE ALSO is worse than none — it gives false confidence.
Edge cases
- The constant is a TypeScript
as constexported from one file. If all consumers import the symbol (not the value), the compiler enforces the invariant — no audit needed. But if any consumer copy-pasted the value as a literal (often in test fixtures or JSON), grep the raw value to catch those. - The constant changed unit (60s → 3min instead of 60s → 180s). Add the new unit-suffixed shape to the grep list. Old comments with the old unit are now drift; update them.
- The repo has migrated from raw values to named symbols mid-history. Grep both shapes; older sites may still carry the raw value.
- The constant is platform-conditional (
isWindows ? 240 : 1). Audit each branch separately. The Windows branch and the POSIX branch are two coupled invariants, not one.
Outputs
- Audit report (above shape) emitted to chat or written to the active retro / handoff result artifact.
- Proposed SEE ALSO repairs, or actual updated comments when repair is authorized (bidirectional trail).
- File path + line number for each MISSED site (so the caller knows where to patch).
- Proposed intent comments at divergent sites, or actual
// Intentionally different from <other-site>: <reason>comments when repair is authorized.
Pairings
- Before
/cold-review: the audit closes the most common Critical finding category ("missed coupled site"). Run audit first; cold-review confirms the audit was thorough. - After a budget raise, page-size change, or magic-number tweak: standard hygiene. Treat this skill the same way you treat the typecheck — automatic.
- Inside
/handoff-executePhase 4 (Execute): when the brief involves a budget / timeout / threshold raise, invoke this audit as part of the execute phase, not as an afterthought.
Out of scope
- This skill does NOT find new constants that should be coupled but aren't yet (e.g., two unrelated files independently hardcoding the same retry value). That's an
improve-codebase-architecturejob (extract-constant refactor). - This skill does NOT enforce future drift. The SEE ALSO trail it repairs will decay again over time. Periodic re-audit is the price of human-maintained cross-references.
- This skill does NOT replace a typecheck-enforced
as constextraction when it's feasible. Prefer language-level enforcement when the constant is purely internal; this skill handles the cases where extraction isn't practical (external interfaces, cross-package fixtures, comment-embedded values).
Human output. This skill's handler-facing output obeys the human-output contract (
human-output/SKILL.md).
Self-improvement. On completion, run the Self-Improvement Protocol (
self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Files (open-skills)
-
SKILL.md 12 KB
--- name: audit-coupled-constant description: Audit every site of a constant whose value is duplicated across multiple call sites (retry budgets, timeouts, page sizes, magic numbers, feature flags). The author-maintained `SEE ALSO` trail is documentation, not enforcement — one missed site means the trail lies. Trigger on /audit-coupled-constant, "audit budget consistency", "find all sites of this value", "check coupled invariant", "before raising this constant", or after any edit to a constant that has SEE ALSO cross-references in its comments. Pairs naturally before /cold-review on a "raise the budget" PR. Not for extract-constant refactors that consolidate scattered values into a single named import — use /improve-codebase-architecture. Not for constants enforced by the type system (TypeScript `as const` literal imported everywhere) where the compiler is the audit — skip. runtime: [claude, codex, agents] visibility: public self-improvable: true next-skills: - skill: cold-review phrase: "/cold-review" why: "After the audit finds (or confirms zero) missed sites, a fresh-context review is the strongest sanity check that the coupled change is consistent." - skill: insight-critique phrase: "/insight-critique" why: "If the audit surfaces ambiguous sites (intentionally different vs. drift), a focused critique on the specific divergence resolves it before commit." triggers: - "/audit-coupled-constant" - "audit budget consistency" - "find all sites of this value" - "check coupled invariant" - "before raising this constant" --- # /audit-coupled-constant Before declaring an edit to a coupled constant complete, grep the constant's value globally to verify every site moved together. The author-maintained `SEE ALSO` trail is a maintenance contract, not enforcement — when one site is missed, the trail silently lies in the other sites. > **Origin.** This skill emerged from a cold-review finding. A 60s retry budget was raised to 180s across 3 of 4 call sites; the 4th (`packages/<pkg>/src/flows/rename.ts:297`) was missed because the SEE ALSO comments in the 3 known sites never mentioned it. Two independent cold reviewers caught it via global grep; the original diagnosis trusted the SEE ALSO trail. The lesson generalizes far beyond retry budgets. ## Boundary Use `audit-coupled-constant` when you are about to declare done on an edit that touches a constant whose value is duplicated across multiple files, OR whose comments name other files via "SEE ALSO" / "keep in sync" / "matches" / "mirrors" cross-references. Common shapes: - Retry / timeout budgets (`240 × 250ms`, `60_000`, `60s`) - Pagination page sizes / query limits (`PAGE_SIZE = 25`) - Feature-flag strings or keys - Magic numbers reflecting external invariants (max upload size, max URL length, schema version) - Shared regex patterns or validation thresholds Do NOT use for constants that are truly local to one file, for purely-imported constants where only the import site moved (the named symbol is the single source), or for constants enforced by the type system (e.g., a TypeScript `as const` literal imported everywhere — the compiler is your audit). ## Authority An audit request authorizes inspection and a chat report, not code, comment or artifact writes. In audit-only mode, Steps 3–4 identify proposed repairs and the report records them as pending. Apply repairs or save a report only where current authorization already covers the exact effects and scope; reuse that authorization without another prompt. Do not claim an audit is a completed repair. ## Step 1 — Identify the constant + its shapes A coupled constant appears in code under multiple shapes. List every shape you might find before grepping: - **Raw value** in code: `240`, `60_000`, `0.5`, `"warn"` - **Named symbol** (if extracted): `RETRY_BUDGET_MS`, `MAX_PAGE_SIZE` - **Value-as-comment** in documentation: `// 60s budget`, `/* 240 × 250ms */` - **Unit suffix** in documentation: `60s`, `60000ms`, `1min` - **Composite expressions** that reduce to the value: `60 * 1000`, `1000 * 60 * 60` - **String tokens** the value participates in: log lines, error messages, JSON fixtures, test names Write the list of shapes down before grepping. Missing a shape is the most common cause of a missed site. ## Step 2 — Grep each shape across the relevant scope Run a separate grep for each shape. Use Grep / ripgrep, not find or recursive Read. Examples: ```bash # Choose the actual justified scope; these rg examples do not imply a type filter. rg -n '\b240\b' <scope> rg -n -i -F '60s' <scope> rg -n '240\s*\*\s*250' <scope> rg -n -F 'RETRY_BUDGET_MS' <scope> ``` For every shape, record the actual command, searched scope, exit status, hits and any failed/unrun search. An unavailable or unrun search remains a coverage gap; do not declare the audit complete. Explain any file-type exclusions, including docs/fixtures/scripts, against the actual affected invariant. Set the scope to the package or repo level — coupled constants often span src + tests + scripts. For monorepos, audit each affected package. ## Step 3 — Reconcile the hits Group hits into three categories: - **Moved together** — site already updated to the new value as part of your edit. ✓ No action. - **Missed site** — site still holds the old value but should move. **Update + verify** the SEE ALSO chain mentions this site after the update. - **Intentionally different** — site holds a different value by design (e.g., test budget intentionally wider than prod, or development tier intentionally lower). **Document the intent** at the site itself with a comment like `// Intentionally different from registry-reset.ts: tests need 3× the budget for singleFork load.` This prevents the next auditor from misclassifying it. If you cannot tell which category a site belongs in, halt the edit and ask the author or git blame the comment that introduced the value. ## Step 4 — Repair the SEE ALSO trail Apply this step only for authorized repairs; otherwise report the proposed trail changes. For any newly-found coupled site, add bidirectional SEE ALSO comments so the next auditor doesn't have to re-discover the relationship: ```typescript // SEE ALSO: <other-file-1>.ts <function> — keep budgets in sync (180s). // SEE ALSO: <other-file-2>.ts <function> — keep budgets in sync (180s). ``` Critically: also UPDATE the SEE ALSO comments in the EXISTING sites to mention the newly-found site. The trail must be bidirectional, or the next person to touch any one site won't know to look at the new one. ## Step 5 — Emit the audit report Brief, structured. One section per scope swept: ``` audit-coupled-constant report constant: <name or value> shapes searched: 240, 60_000, 60s, RETRY_BUDGET_MS scope: packages/<pkg> sites found: 4 src/flows/registry-reset.ts:90 moved together ✓ src/scaffold/delete.ts:42 moved together ✓ tests/_helpers/fs-retry.ts:47 moved together ✓ src/flows/rename.ts:297 MISSED — update + add SEE ALSO trail intentionally-different sites: 0 SEE ALSO trail updated: no (audit-only; propose adding rename.ts to the 3 existing sites) ``` ## Rules - MUST list every shape the constant can appear in (raw value, named symbol, unit-suffixed comment, composite expression, embedded in strings) before grepping. - MUST run a separate grep for each shape — one grep per shape, not a single broad grep. - MUST classify each hit into moved-together / missed / intentionally-different. Halt the edit if you can't classify confidently. - For authorized repairs, MUST update SEE ALSO comments in the existing sites when you find a new site; the trail must be bidirectional. Audit-only mode reports the missing links without changing them. - MUST NOT trust SEE ALSO comments as enforcement. They are documentation that decays. - MUST NOT declare an edit done before the audit report shows all sites moved (or are intentionally-different with explicit documentation). - SHOULD pair with `/cold-review` for high-stakes coupled-constant edits (retry budgets that ship to users, schema versions, feature flags wired into rollouts). ## Anti-patterns - **"I updated the SEE ALSO sites — done."** The SEE ALSO trail's set of named sites may be a subset of all coupled sites. Grep first; trust the trail second. - **Trusting word-boundary grep for short numbers.** `240` matches `1240`, `2403`, etc. without `\\b`. Always use word-boundary for digit-only constants under 1000. - **Skipping the unit-suffixed comment shape.** Many sites carry the value as a comment (`// 60s budget`) even when the code uses a named symbol. Comments don't move with code refactors and are the silent-drift source. - **Treating intentionally-different as "moved together — skip."** If the site is intentionally different, the comment at the site must say so. Otherwise the next auditor will flag it as drift and the cycle repeats. - **Auditing only your own edit's scope.** The constant may appear in a test fixture, a doc snippet, a script, or a docstring inside a sibling package. Audit the whole repo unless you can prove a tighter scope. - **Adding SEE ALSO to the new site without updating the old sites.** Trail must be bidirectional. One-way SEE ALSO is worse than none — it gives false confidence. ## Edge cases - **The constant is a TypeScript `as const` exported from one file.** If all consumers import the symbol (not the value), the compiler enforces the invariant — no audit needed. But if any consumer copy-pasted the value as a literal (often in test fixtures or JSON), grep the raw value to catch those. - **The constant changed unit (60s → 3min instead of 60s → 180s).** Add the new unit-suffixed shape to the grep list. Old comments with the old unit are now drift; update them. - **The repo has migrated from raw values to named symbols mid-history.** Grep both shapes; older sites may still carry the raw value. - **The constant is platform-conditional** (`isWindows ? 240 : 1`). Audit each branch separately. The Windows branch and the POSIX branch are two coupled invariants, not one. ## Outputs - Audit report (above shape) emitted to chat or written to the active retro / handoff result artifact. - Proposed SEE ALSO repairs, or actual updated comments when repair is authorized (bidirectional trail). - File path + line number for each MISSED site (so the caller knows where to patch). - Proposed intent comments at divergent sites, or actual `// Intentionally different from <other-site>: <reason>` comments when repair is authorized. ## Pairings - **Before `/cold-review`:** the audit closes the most common Critical finding category ("missed coupled site"). Run audit first; cold-review confirms the audit was thorough. - **After a budget raise, page-size change, or magic-number tweak:** standard hygiene. Treat this skill the same way you treat the typecheck — automatic. - **Inside `/handoff-execute` Phase 4 (Execute):** when the brief involves a budget / timeout / threshold raise, invoke this audit as part of the execute phase, not as an afterthought. ## Out of scope - This skill does NOT find new constants that should be coupled but aren't yet (e.g., two unrelated files independently hardcoding the same retry value). That's an `improve-codebase-architecture` job (extract-constant refactor). - This skill does NOT enforce future drift. The SEE ALSO trail it repairs will decay again over time. Periodic re-audit is the price of human-maintained cross-references. - This skill does NOT replace a typecheck-enforced `as const` extraction when it's feasible. Prefer language-level enforcement when the constant is purely internal; this skill handles the cases where extraction isn't practical (external interfaces, cross-package fixtures, comment-embedded values). > **Human output.** This skill's handler-facing output obeys the human-output > contract (`human-output/SKILL.md`). > **Self-improvement.** On completion, run the Self-Improvement Protocol (`self-improve/SKILL.md`): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.