thkt/census

/census - DR Gaps Audit

Input

$ARGUMENTS is an optional path naming the audit scope. No argument means the whole repository, a file path mines that file alone, and a directory path limits the scope to that subtree. Skip the doc phases when the target is a single source file. When scoped to a path, record the target in the report Summary's Scope row.

Decision Criteria

Impact / reversibility, the incomplete-contract definition, the DR-worth rule of thumb, and the challenge angles all live in ${CLAUDE_SKILL_DIR}/references/decision-criteria.md. Each phase applies it as the basis for judgment.

Phase 1: Source File Listing

If a file is named directly, skip this phase and pass that file to Phase 3. Otherwise run python3 ${CLAUDE_SKILL_DIR}/scripts/list-source-files.py <scope> to list the source files. <scope> is the directory when one is given, the repository root when no argument is passed.

When the file count exceeds the guideline of 20, confirm narrowing via AskUserQuestion before the Phase 3 reviewer fan-out. Adjust the guideline to repository size; options are a subdirectory, top-N, or a specific module. At or below the guideline, skip the prompt and pass the full list to Phase 3.

Phase 2: Document Detection

Skip this phase when the target is a single source file. With a directory target, scope to that subtree; with no argument, scan top-level and docs/. Look for decision-bearing documents using the patterns in ${CLAUDE_SKILL_DIR}/references/detection-targets.md.

Phase 3: Source File Decision Mining

Gather evidence from two channels per source file. The reviewer covers code-internal evidence, census covers git history.

3a Reviewer mining

For each source file, spawn the reviewer subagent matching its language via Task. The reviewer answers the following.

• Why does this file have this granularity and shape?
• What invariant or contract does it carry that a reader cannot derive from the code?
• Is there a comment or module-doc that records the rationale?
• Does the comment describe only the current state and omit the rule for future contributors, matching the incomplete-contract pattern?

3b Commit message mining

The reviewer has no git access, so census itself runs git log --follow --format='%h %s' -- <file> and extracts commits containing decision verbs. The decision verb list is in detection-targets.md.

3c Recording and DR cross-reference

Record each finding as file:line + decision summary + evidence + documented? + incomplete-contract?. Evidence is one of comment / naming / module-doc / commit. Commit-sourced findings use commit <sha> as evidence. After collecting findings, cross-reference against the DR directory if any, drop findings already covered by a DR, and record the excluded count in Summary as "DR-covered (excluded)".

Phase 4: Prose Decision Extraction

For each detected document, find sentences containing decision verbs; each match is a candidate. Cross-reference against DRs as in 3c and drop covered candidates.

Phase 5: Ranking and Challenge

5a Tagging and Initial Ranking

Tag each candidate from Phase 3 and Phase 4 with impact and reversibility. DR promotion candidates satisfy (impact = H) AND (reversibility = low OR medium).

Findings with incomplete-contract=Yes are promoted regardless of documented? value. Other findings are recorded but not promoted.

5b Devil's Advocate Challenge

Spawn critic-design via Task with the initial promotion candidate list and ${CLAUDE_SKILL_DIR}/references/decision-criteria.md. critic-design challenges each candidate with the challenge angles and returns one of keep / downgrade / drop. Record the verdict alongside the initial ranking.

Phase 6: Report Output

Write the report following ${CLAUDE_SKILL_DIR}/templates/report-template.md, substituting placeholders from findings. Add a single repo-wide summary line keep N / downgrade N / drop N right after the DR Promotion Candidates table. After writing, print a console summary: candidate count, DR promotion candidate count.

mkdir -p docs/audit
STAMP=$(date -u +%Y-%m-%d-%H%M%S)  # UTC date + HHMMSS; same-day reruns never collide
REPORT="docs/audit/${STAMP}-dr-gaps.md"

Hand-off

• Print only the post-challenge keep candidates and offer /dr for each, or aggregate them into a single tracking issue via /issue
• List downgrade candidates as comment-strengthening tasks. Record drop candidates in the report only, not as follow-up
• This skill only mines and nominates. DR drafting goes to /dr, drift scan against existing DRs to /adrift, code changes and README updates are out of scope
• In a repo that already has DRs, run /adrift first, then use this skill to mine the gaps drift cannot see

Completion Criteria

Finish only when all of the following hold. Record the reason for any unmet item in the report.

| Item | Condition | | ----------- | ------------------------------------------------------------------------------------ | | Report | docs/audit/<YYYY-MM-DD>-<HHMMSS>-dr-gaps.md exists | | Source file | Every reviewed file is accounted for. No-decision files may be batched into one line | | Document | Every scanned document has an extraction section. "no decisions found" is acceptable | | Tags | Every candidate has impact + reversibility | | Candidates | DR promotion candidates listed at the end with a one-line rationale |