Files
skillshare/wiki/audit.md
T
Willie 262e639701 docs: add task-routed agent wiki
Add a shared instruction kernel and byte-budgeted topic router so agents load only task-relevant repository guidance. Wire drift checks into local and CI workflows and point project skills at the routed topics.
2026-09-25 02:32:37 +08:00

2.6 KiB

Codebase Consistency Audit

Use when asked to audit the codebase, flags, documentation, tests, targets, handler splits, oplog coverage, or Web API consistency. This topic is read-only: report findings without modifying files.

Evidence Rules

  • Give every finding a file path, line number, and direct evidence.
  • Search before deciding so naming differences do not become false positives.
  • Base conclusions on current code and configuration rather than stale documentation or memory.
  • When the user names a dimension, inspect only that scope. Run every dimension only for a full audit.

Dimensions

CLI Flags

Compare flag, usage, and argument definitions in cmd/skillshare/*.go with website/docs/reference/commands/*.md:

  • UNDOCUMENTED: present in code but absent from documentation.
  • STALE: documented but absent from code, or behavior has changed.
  • OK: name, mode, default, and semantics agree.

Specifications and Tests

  • For completed specs/, verify the implementation and testable acceptance criteria.
  • For each command handler, inspect unit and integration coverage. A matching filename alone does not prove coverage.
  • Use IMPLEMENTED/MISMATCH/PENDING and COVERED/PARTIAL/MISSING classifications.

Targets and Schemas

Inspect internal/config/targets.yaml for names, aliases, global/project paths, and collisions, then compare configuration validation, schemas, and target tests. Never assume every target supports the same resource kinds.

Handler Split

Find large cmd/skillshare/*.go files and verify that dispatch files contain only flags and mode routing while core logic, rendering, prompts, TUIs, batching, and resolution follow cli-development conventions. Roughly 300 lines is a review trigger, not an automatic failure.

Oplog

Mutating commands should write the operations log; read-only commands should not write merely for consistency. Inspect success and error paths, duration, arguments, and the audit-log boundary. Determine which commands mutate state from current behavior rather than a fixed historical list.

Web API

Compare routes in internal/server/server.go, handler_*.go files, handler tests, and ui/src/api/client.ts. CLI-only or API-only behavior may be intentional; inspect the product surface before reporting an issue.

Report

Use a concise table for each dimension:

Item Status Evidence Impact

End with confirmed issues, intentional differences, uncertainty, and recommended priority. Do not fix findings during an audit. If the user later requests fixes, load the appropriate implementation topic.