verify-docs · diff
git:20260610.be2a852 to git:20260610.c15894f
98 added, 4 removed. Audit A to A.
---
name: verify-docs
description: "Periodic doc verification — runs validate.sh structural check, samples assumption rows for semantic review. Run quarterly to collect drift evidence."
effort: low
keywords: [verify, docs, assumptions, drift, semantic, freshness, quarterly]
task_strategies: [investigation]
stream_affinity: [docs, tech-debt]
argument-hint: "[--sample N] [--json] [--seed N]"
group: brana
model: haiku
allowed-tools:
- Bash
- Read
- AskUserQuestion
status: stable
growth_stage: prototype
---
+ # Verify-Docs — Periodic Doc Verification
- <!-- PROCEDURE_FILE: procedures/verify-docs.md -->
- This skill's full procedure is in a separate file for startup performance (ADR-034).
- Read and execute `../../procedures/verify-docs.md` resolved against this skill's base directory (the path announced when the skill loads) — i.e. `{base-dir}/../../procedures/verify-docs.md`. This form is valid in both the repo layout and the deployed-plugin layout.
- If the path doesn't resolve, use Glob to find `**/procedures/verify-docs.md`.
+ Run a structural assumption-freshness check + surface a random sample of assumption rows for manual semantic review. **No LLM.** This is the trigger-evidence collector for t-441 (LLM-assisted drift detection).
+
+ ## When to use
+
+ - **Quarterly** — primary cadence. Run both `--scope docs` and `--scope claudemd`.
+ - **Before a major architecture change** — sanity-check assumption claims in the docs you're about to revise.
+ - **After a tier backfill** — confirm structural staleness clears with the new tiers.
+ - **After a CLAUDE.md edit** — run `--scope claudemd` to confirm no volatile content was introduced.
+ - **On demand** — when you suspect a doc says X but code does Y.
+
+ ## Process
+
+ ### 1a. Run the structural + sampling check (scope: docs)
+
+ ```
+ Bash: bash system/scripts/verify-docs.sh --sample 5
+ ```
+
+ If you want reproducibility, pass `--seed N`. For automation/scripting:
+
+ ```
+ Bash: bash system/scripts/verify-docs.sh --json --sample 5 > /tmp/verify-docs-$(date -I).json
+ ```
+
+ ### 1b. Run the CLAUDE.md portfolio scan (scope: claudemd)
+
+ ```
+ Bash: bash system/scripts/verify-docs.sh --scope claudemd
+ ```
+
+ Detects three violation types across all portfolio `CLAUDE.md` files (excluding worktrees):
+ - **DATED_STATUS** — status lines with embedded 202X-MM-DD dates
+ - **PRICING** — service cost lines (`ARS N/mes`, `$N/mes`)
+ - **TRACKER_TABLE** — work-tracker tables (Status + Priority/Effort/Sprint/Assigned)
+
+ For JSON output: `bash system/scripts/verify-docs.sh --scope claudemd --json`
+
+ ### 2. Read the sample
+
+ Each sample entry shows:
+ - `doc` — the file
+ - `tier` — effective tier (architecture / methodology / tech) and source (per-row, doc, or default)
+ - `verified` — the row's last_verified date
+ - `claim` — the assumption text (truncated to 100 chars; read the full row in the source doc)
+
+ For each sample row:
+ 1. Read the claim. Open the doc. Read the full row context.
+ 2. Check the implementation: does the code/system still behave as the claim says?
+ 3. Mark drift: `y` (drifted — claim is wrong) or `n` (still true).
+
+ Record results — a checklist works:
+
+ ```
+ [N] verify-docs run on YYYY-MM-DD
+ - doc#1 — claim: "..." — drift: n
+ - doc#2 — claim: "..." — drift: y (now does Z, not Y)
+ - doc#3 — ...
+ - doc#4 — ...
+ - doc#5 — ...
+
+ Drift rate: 1/5 = 20%
+ ```
+
+ ### 3. Decide
+
+ - **Drift rate ≤ 20%** — structural checks are sufficient. File errata/fix tasks for any drifted claims. Done.
+ - **Drift rate > 20%** — escalate. Update `t-441` notes with the rate and unblock it. Build the LLM-assisted check; the manual sample alone is too lossy.
+
+ ### 4. Persist the result
+
+ Append a one-line entry to the field log so quarterly trends are visible:
+
+ ```
+ Bash: echo "$(date -I) verify-docs N/5 drift" >> docs/field-notes/verify-docs-log.md
+ ```
+
+ (File is created on first run; no scaffolding needed.)
+
+ ## Outputs
+
+ - Console output (or JSON) with structural + sample.
+ - Optional: append to `docs/field-notes/verify-docs-log.md`.
+ - For each drifted claim: a backlog task to fix the doc or the code.
+
+ ## Out of scope
+
+ - LLM semantic check — that's t-441. Build it only after this skill collects evidence the manual approach is insufficient.
+ - Continuous monitoring — verify-docs is a periodic surface, not a hook.
+ - Cross-repo verification — only scans `docs/` in the current repo.
+
+ ## Reference
+
+ - Spec: `system/scripts/verify-docs.spec.md`
+ - Backing script: `system/scripts/verify-docs.sh`
+ - Tests: `tests/scripts/test-verify-docs.sh`
+ - Frontmatter spec: `docs/architecture/features/doc-frontmatter-spec.md`
+ - Trigger-gated next step: `t-441` (LLM-assisted drift detection)