create-pmos 0.6.3 → 0.7.0

package/workspace/skills/doc-review.skill

@@ -0,0 +1,114 @@
+---
+name: doc-review
+label: "Review documents"
+description: "Read the planning documents you name and report only defects the artifact cannot detect about itself — never lint. Each finding carries its evidence and, where one exists, a proposed change you dispose of."
+run: agent
+agent: claude
+output:
+  - Read
+  - Findings
+  - Withheld
+---
+
+You are running the "Review documents" skill in this PMOS workspace (local, file mode). Work only
+from this repository's own files, git, and CLIs — no network (D54).
+
+Goal: surface defects in the named documents that **the artifact cannot detect about itself**, and
+file them as a contract-checked review the PM disposes of one at a time.
+
+## What counts as a finding — and what does not
+
+The whole value of this review is that the PM keeps reading it. A review that reports what a linter
+already reports becomes a linter with manners, and gets ignored by Thursday.
+
+**Report only defects the document cannot detect about itself.** The four kinds that recur:
+
+- **A metric that does not measure its own claim** — a PRD bets on an outcome, then defines success as
+  a capability demo, so it can score full marks and move the outcome not at all.
+- **An anchor that cannot score wrong** — a rubric dimension whose anchors award credit for descoping,
+  or that cannot distinguish a correct implementation from an absent one.
+- **A gate that scripts away its own question** — a rubric prescribing the Acceptance Gate as the same
+  checklist it already scored, turning D12's strategic judgement into a second review pass.
+- **A constraint contradicted elsewhere** — a non-goal or design rule in one shipped document that
+  silently rules out what another document proposes.
+
+**NEVER report** — these belong to lint and the Frontmatter Gate, and emitting them fails the
+contract outright: frontmatter or schema validity · broken links or missing paths · string/regex
+matches · counting occurrences · spelling, typos, formatting.
+
+**Say nothing when there is nothing to say.** An empty findings list is a correct and valued outcome.
+Do not pad a review to look thorough — a false finding costs the PM more than a missed one, because
+they pay for it every time.
+
+## The withheld class — where you must NOT propose a fix
+
+Some defects are not defects. Before proposing any change, ask: **would applying this close a
+question the PM has parked, or overwrite a decision they recorded?** Check `pm-decisions.md`,
+`DECISIONS.md`, and the document's own history.
+
+If yes, the finding is **withheld**: `"withheld": true`, `"proposal": null`, and a
+`"withheld_reason"` saying why it is the PM's to settle. The client renders no Apply control for it —
+the absence of the button is the guard, so a withheld finding carrying a proposal is rejected by the
+contract, not merely discouraged.
+
+The recorded instance: `CLAUDE.md` points file-mode state at `pmos/state/*.jsonl`, which looks stale
+and is not — it is a measured open question (`pm-decisions.md` 491–503).
+
+## Procedure
+
+1. **Take the scope.** Read exactly the documents the PM named. Do not widen it.
+   *Done when:* every named path has been read in full, and you can list them.
+
+2. **Find, then cut.** For each document, ask the four questions above. Then remove every candidate
+   that a regex could have found, and every one you cannot evidence to a specific line.
+   *Done when:* each surviving finding names, in one sentence, what the artifact cannot see about
+   itself — the `self_undetectable` field. If you cannot write that sentence, drop the finding.
+
+3. **Propose, or withhold.** Where a change would genuinely fix it, write `proposal.before` as text
+   copied **verbatim** from the file and `proposal.after` as its replacement. `before` must appear in
+   the file **exactly once** — the apply path refuses a stale or ambiguous anchor rather than
+   guessing. Where the withheld test fires, propose nothing.
+   *Done when:* every finding either carries an exact-match proposal or is explicitly withheld.
+
+4. **File the review.** Pick a run id (`doc-review-<UTC-timestamp>`), then write
+   `workspace/state/reviews/<run-id>.json` with exactly this shape:
+
+   ```json
+   {
+     "at": "<ISO 8601>",
+     "read": ["planning/prd/example-prd.md"],
+     "findings": [
+       {
+         "title": "One sentence, the defect stated plainly.",
+         "file": "planning/prd/example-prd.md",
+         "kind": "metric-claim-mismatch",
+         "argument": "Why this is a defect — the reasoning, not a restatement.",
+         "self_undetectable": "What this artifact cannot see about itself.",
+         "evidence": [{ "file": "planning/prd/example-prd.md", "line": 17 }],
+         "withheld": false,
+         "proposal": { "before": "<verbatim text from the file>", "after": "<replacement>" }
+       }
+     ]
+   }
+   ```
+
+   `withheld` is a required boolean on every finding and is never inferred. A withheld finding sets
+   `"proposal": null` and adds `"withheld_reason"`.
+   *Done when:* the file is valid JSON and `GET /api/review` returns `ok: true` for it. If it returns
+   `422`, the contract rejected a finding — fix it; do not file it anyway.
+
+5. **Tell the PM it is ready.** Read `workspace/state/needs.json` (a missing file is `[]`), append
+   exactly this object, and write the whole array back — it must stay a valid JSON array:
+
+   ```json
+   {"run_id":"<run-id>","kind":"review","initiative_id":"workspace-review-and-edit","question":"Document review — <n> findings"}
+   ```
+   *Done when:* `needs.json` is a valid array containing the new object.
+
+## Output contract — produce EXACTLY these sections
+
+- **Read** — the documents actually read, one per line.
+- **Findings** — one line per finding: the title and its `file:line`. `None this review.` if empty,
+  which is a good outcome, not a failed run.
+- **Withheld** — findings deliberately left for the PM, with the one-line reason. `None this review.`
+  if empty.