Repo Asset Stocktake

repo-asset-stocktake — Non-Code Asset Value Stocktake

Audit a project repository's non-code assets — configs, CI workflows, runbooks, and other files that tooling or humans consume — and assign each a holistic Keep / Update / Retire / Merge verdict. Evaluation is single-context and holistic; there is no runtime script and no numeric score.

Design note 1 — every asset has a consumer. A non-code asset is not alive because it exists; it is alive because something consumes it — a tool invoked from a build script, a CI runner fired by an event, a human who reaches it through a link. When the consumer vanishes, or the asset stops serving the consumer it was written for, the asset becomes a review candidate. The config / workflow / runbook classes below are three seed consumer-classes, not the closed set — add a row whenever you meet a new consumer.

Design note 2 — two tiers, code then judgment. Reachability is structural (decidable by grep/find) so tier-1 enumerates it as code. Value is semantic ("does this still mean anything?") so tier-2 leaves it to holistic LLM judgment. The deterministic scan narrows the gray zone, and the LLM judges only what survives. An asset can be perfectly reachable and still be dead (a workflow that fires but runs a no-op, a runbook that is linked but describes a retired process); tier-1 cannot see that, which is exactly why tier-2 exists.

Modes ($ARGUMENTS)

$ARGUMENTS is [full|changed] [REPO_DIR] — mode first (default full), optional repo path (default the current working directory).

Phase 1 — Inventory + tier-1 reachability

Enumerate assets, then measure each consumer's reachability with inline grep/find. Detection is structural → code. Use throwaway shell; do not bundle a script until the same scan demonstrably repeats across runs.

Exclude VCS, dependency, build, and cache trees from both enumeration and grep — .git/, node_modules/, .pytest_cache/, vendor/, dist/, build/, report/cache dirs. Assets there are vendored or generated, not authored, and pollute the inventory with false candidates.

Seed consumer-classes (extend as needed):

Count only real consumption edges — a mention in a comment, a changelog, or an old ADR does not keep an asset alive (it fools a naive "the name appears somewhere" grep into a false-alive verdict). References cross language boundaries (config→CI shell, doc→doc), so scope the grep to the whole repo, not one language's source tree.

Record per asset — its consumer class and a one-line reachability fact (e.g. "0 invocation sites", "referenced script ci/build.sh deleted", "3 inbound links").

Phase 2 — Evaluation (fully inline, holistic)

Judge each asset in one context. No numeric score, no rubric, no aggregation into a grade.

Stage 1 — binary screen (surface only the No answers)

For each asset ask, Yes/No:

• Is its consumer still present? (tool invoked / trigger reachable / at least one inbound link)
• Does its content still describe something that currently exists? (the process it documents / the check it configures / the job it runs is still real)
• Is it distinct from every other asset? (not a superseded duplicate)
• Would a reader who opened it today act on it correctly? (not misleading-because-stale)

An asset that answers Yes to all is a Keep — do not belabor it. Surface only the assets with a No.

Stage 2 — verdict pressure-test (non-Keep only)

For each surfaced asset, ask 1–3 refutation questions before committing a verdict:

• Retire candidate — "Is there a consumer I failed to grep (a dynamic invocation, an external wiki link, a scheduled trigger)? If I delete this, what breaks?"
• Update candidate — "Is the asset itself wrong, or is only my reachability grep incomplete? Is the fix mechanical (repair the trigger, fix the ref) or a content rewrite?"
• Merge candidate — "Which surviving asset absorbs this one, and does the merge lose anything?" This is also where superseded-duplicate workflows are judged (two workflows whose steps/intent overlap) — it needs content comparison, so it belongs here, not in the tier-1 scan.

Verdict meaning

Mandatory-surface rule. Any asset whose tier-1 reachability is zero (0 invocation sites / all references dead / 0 inbound links) MUST be surfaced as at least a Retire candidate — reachability zero is never silently a Keep. This is the opposite of skill-stocktake's stance, deliberately: there, zero usage never creates a candidate, because a skill can be valid and simply unfired. Here the measure is reachability — no invocation site, every reference dead — which is a structural fact about the repo, not a behavioural one about the model, so it does create a candidate. (rules-stocktake's absorption rule is the same kind of structural test.)

Evaluate origin-blind — who wrote the asset, or how long it took, does not bear on whether it still earns its place.

Phase 3 — Summary

One table, most-actionable first:

Close with a one-line count — total assets, and how many Keep / Update / Retire / Merge — plus the delta since the previous audit if results.json exists.

Phase 4 — Consolidation

Confirm one by one (config-gc's confirm-each design). Walk the non-Keep candidates sequentially; show the evidence first, then ask [y/n/skip]. Never batch the approval — "Retire all 6? [y/n]" defeats the design. skip records the verdict without acting.

• Retire — soft-delete first, never an autonomous hard-delete. Rename to <file>.disabled or move to a repo-local trash; real deletion is a later, separate human step. Offer adr-writer when the retirement encodes a decision worth recording.
• Update — apply mechanical fixes inline after confirm (repair a broken on: trigger, fix a dead uses: / run: ref, delete a stale config key). Flag prose-heavy content rewrites (a runbook describing a changed process) for the user or a writing skill rather than guessing the new content.
• Merge — consolidate into the surviving asset, then soft-delete the absorbed one.

Reason quality (required)

Every reason must stand alone — a reader who did not run the scan should understand why from the row. Cite the concrete reachability fact.

• ❌ Bad — "Retire — unused." / "Update — stale." (states the verdict, not the evidence)
• ✅ Good — "Retire — .stylelintrc names a tool absent from package.json, CI, and pre-commit since the CSS pipeline was removed; nothing invokes it."
• ✅ Good — "Update — deploy.yml still fires on push but its run: ./scripts/release.sh target was deleted; repair or point it at the new path."
• ✅ Good — "Merge — ci-lint.yml and lint.yml both run the same ruff/black steps on push; fold ci-lint.yml into lint.yml and retire it."
• ✅ Good — "Keep — RUNBOOK.md is linked from README and its rollback steps still match the current deploy job."

results.json (lean ledger)

Persist verdicts so changed mode can carry them forward. Written inline via Read/Write — never a script. The ledger lives inside the audited repo at REPO_DIR/.repo-asset-stocktake.json (not under the skill folder) — one ledger per repo, so auditing multiple repos never clobbers a shared file and changed mode's evaluated_at is scoped to the repo it belongs to. Suggest adding it to the repo's ignore file if it should not be committed.

{
  "evaluated_at": "2026-07-05T12:00:00Z",
  "repo": "<REPO_DIR>",
  "assets": [
    {
      "path": ".textlintrc",
      "consumer": "tool-invocation",
      "reachability": "0 invocation sites",
      "verdict": "Retire",
      "reason": "textlint absent from package.json/CI/pre-commit; config inert",
      "action": "pending | soft-deleted | skipped"
    }
  ]
}

evaluated_at is an ISO-8601 UTC stamp (date -u +%Y-%m-%dT%H:%M:%SZ). To find the modified set in changed mode, prefer git (git diff --name-only / git log --since) when the repo is version-controlled — clone/checkout reset mtimes, so find -newermt comparisons mislead in git-managed trees even though the flag itself works on BSD/macOS find — or parse evaluated_at and compare each asset's mtime in the agent's own logic. Carry a prior row forward only when its asset is both unmodified and its tier-1 reachability is unchanged vs the prior ledger — an asset whose reachability dropped to zero while its own file was untouched must be re-judged, never left a silent stale Keep.

Related

• refactor-clean — its Non-Code Assets sweep covers code-consumed data (files a program loads by glob/registry); its test is structural — whether any consumption edge exists at all. This skill covers non-code-consumed assets (tool / CI / human consumers) and judges semantic value — an asset can have a live edge and still be dead (a workflow that fires but no-ops). Structural deadness → refactor-clean; diminished value → here.
• context-sync — audits the four documentation roles (CLAUDE.md / graph.jsonld / ADR / README) for placement overlap and freshness against code. Runbooks are the overlap zone — context-sync asks "is this doc in the right role and consistent with the code," this skill asks "does this doc still describe something that exists / earn its place at all."
• config-gc — GC over ~/.claude harness config (hooks / permissions / MCP / cache). This skill targets a project repository — different directory, same confirm-each gate.
• skill-stocktake / rules-stocktake — the same stocktake pattern over a different asset class (installed skills / always-loaded rules). This skill is their sibling for a project repo's non-code assets.
• harness-sync — syncs this origin: shimo4228 skill to its public repo after edits.

References

Binary-question decomposition without score aggregation — the stocktake family's shared basis:

• BinEval "Ask, Don't Judge" — arXiv:2606.27226
• CheckEval — arXiv:2403.18771
• TICK — arXiv:2410.03608