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

52 lines
2.6 KiB
Markdown

# 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.