Skip to content

initial-audit.md

Latest commit

 

History

History
63 lines (39 loc) · 2.83 KB

initial-audit.md

File metadata and controls

63 lines (39 loc) · 2.83 KB

Initial Audit Procedure

An exhaustive review of every doc in a single repo. Expect this to take a full session.

1. Survey the Repo's Docs

Ensure the repo is cloned locally (see "Working with Repos Locally" in CLAUDE.md). Then scan the file tree for documentation files: README.md at any level, docs/**/*, *.md, and any other common doc patterns (wiki links, CONTRIBUTING, CHANGELOG, etc.).

Present the list to the user so they see the scope.

2. Read and Verify Each Doc

Read each doc file from the local clone. Determine what it's documenting — what code, features, APIs, or processes does it describe? Read the relevant source files to verify accuracy.

Look for:

  • Stale references: Functions, classes, endpoints, CLI flags, or config options mentioned in the doc that no longer exist or have been renamed
  • Outdated instructions: Setup steps, build commands, or workflows that no longer work
  • Missing information: Significant features or changes in the code that the doc doesn't cover
  • Broken examples: Code samples that wouldn't work against the current codebase
  • Wrong descriptions: Behavioral descriptions that don't match what the code actually does

3. Check for Missing Coverage

For each doc, find when it was introduced or last substantially updated:

./repo-tools log {owner}/{repo} -1 --format=%H -- {doc_path}

That gives the most recent commit that touched the doc. Then pull the commit messages since that point:

./repo-tools log {owner}/{repo} {doc_last_sha}..HEAD --oneline

Scan those messages for anything that sounds relevant to the doc's topic. For example, if the doc covers authentication and a commit says "add OAuth2 support," that's a hit.

For commits that look relevant, check the affected files in the local clone to confirm whether the doc is missing coverage:

./repo-tools show {owner}/{repo} {sha} --name-only --format=

Flag anything that represents a feature, behavior change, or API addition that the doc should mention but doesn't.

4. Report Findings Per Doc

After reviewing each doc, report findings immediately — don't save everything up for the end. The user should be able to respond doc-by-doc:

  • "Fix it" — suggest a specific edit
  • "Ignore that doc" — add to ignored_docs, won't flag in future weekly checks
  • "That's fine" — no action needed
  • "Skip for now" — add to pending_findings in state/verification.yaml with a short description of the issue, will be surfaced in future sessions

5. Graduate the Repo

When all docs in the repo have been reviewed (even if some findings were skipped), update the repo's status:

  • In state/known_repos.yaml: change status from unaudited to active
  • In state/verification.yaml: record last_verified_date and last_commit_sha (HEAD at time of audit)

The repo is now in the weekly check rotation.