Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
187da0c
feat(doc-set): add the doc-set skill, workflow, and review-page tooling
jth-nw Nov 2, 2026
093751f
fix(doc-set): address CodeQL alerts and code review on the doc-set to…
jth-nw Nov 2, 2026
63903d9
Merge branch 'dev' into feat/doc-set-skill
jth-nw Nov 5, 2026
9f498c5
feat(doc-set): add align mode for versionless products
jth-nw Nov 5, 2026
705d9bd
fix(doc-set): repair the workflow header string and test that it parses
jth-nw Nov 5, 2026
6bb3ad7
fix(doc-set): create the output folder when writing a report or revie…
jth-nw Nov 5, 2026
9212a94
fix(doc-set): keep fact ids when the fact pack is merged again
jth-nw Nov 5, 2026
5078555
feat(doc-set): let a reviewer keep similar facts apart with dedupe.json
jth-nw Nov 5, 2026
6d5d2da
feat(doc-set): let a triage slice propose new pages
jth-nw Nov 5, 2026
7054317
feat(doc-set): list pages the code cannot verify in the author report
jth-nw Nov 5, 2026
7e6f3f8
fix(doc-set): in an align run, verify only the sentences a draft adde…
jth-nw Nov 5, 2026
46ca223
fix(doc-set): never fix a verifier problem by deleting original text
jth-nw Nov 5, 2026
3fb726a
feat(doc-set): lint every page of the version at the end of a run
jth-nw Nov 5, 2026
d9b0249
feat(doc-set): make restyle a separate pass, and keep updated pages f…
jth-nw Nov 5, 2026
316744f
fix(doc-set): resolve CodeQL race and temp-file alerts in align-init
jth-nw Nov 6, 2026
654331f
feat(doc-set): let reviewers reject a page so it can be removed from …
jth-nw Nov 6, 2026
dbd9429
feat(doc-set): explain the whole-page lint in the report and show the…
jth-nw Nov 6, 2026
c8627b3
feat(doc-set): write a missing product brief at intake, before the fa…
jth-nw Nov 9, 2026
b94de44
fix(doc-set): address the PR's code review: kb flag, entry guard, mis…
jth-nw Nov 9, 2026
e2d67c0
Merge branch 'dev' into feat/doc-set-skill
jth-nw Nov 9, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 170 additions & 0 deletions .claude/skills/doc-set/SKILL.md

Large diffs are not rendered by default.

79 changes: 79 additions & 0 deletions .claude/skills/doc-set/references/fact-pack.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Fact pack, claims, manifest, and results

A `/doc-set` run keeps its state in `.doc-set/<product>-<version>/`. All files are JSON. `scripts/doc-set/manifest.mjs validate` checks them; `scripts/doc-set/coverage.mjs` reads them.

## facts.json (from code)

In an align run (a versionless product) `baseline` and `baselineSha` are optional: with no baseline every fact has status `unchanged`, and the manifest has no `from`. `version` is `current`.

```json
{
"product": "pingcastle", "version": "3.6", "ref": "v3.6.0", "refSha": "<sha>", "baseline": "v3.5.0", "baselineSha": "<sha>",
"facts": [
{ "id": "F012", "statement": "The --max-nodes option limits the number of nodes scanned. Default 100.",
"cite": "src/Cli/Options.cs:88", "area": "cli", "status": "new", "internal": false }
]
}
```

- `id`: `F` plus a number, unique in the file.
- `statement`: one customer-visible fact, in plain words, with the exact UI label, option name, default, or limit as the code shows it.
- `cite`: `path:line` in the code at `ref`. Required unless `internal` is true.
- `area`: the feature area. Triage groups pages by it.
- `status`: `new`, `changed`, or `removed` against the merge base; `unchanged` otherwise. A `removed` fact is never written on a page. It tells triage which pages to RETIRE or UPDATE.
- `tickets`: optional list of Jira or ADO keys from the commits that introduced or changed the fact (for example `["TMR-1455"]`). The claims phase uses it to link a ticket to its facts. A fact needs no ticket.
- `internal`: true for what the customer never sees or acts on (class names, build details, tested-on versions, numbers you derived). Follow "Write for the customer" in `.claude/skills/doc-draft/SKILL.md`. Internal facts are listed in the report and left off pages.

Where to look: UI resource and string files, settings and config schemas, CLI help and argument parsers, API specs, installer and requirements files, permission and role definitions, error and log messages the customer reads, and the three-dot diff `baseline...ref` (from the merge base) for what changed.

## claims.json (from Jira)

```json
{ "claims": [
{ "id": "C003", "key": "PLAT-1234", "summary": "Add scan timeout setting",
"status": "confirmed", "facts": ["F012"], "note": "" }
] }
```

- `status`: `confirmed` (a fact backs it; list the fact ids), `contradicted` (the code says otherwise; the code wins and the note says how), `jira-only` (no code evidence yet; it becomes a `{/* TODO */}` and is never written as fact), `not-shipped` (the ticket isn't in this release), `internal` (shipped, but nothing a customer sees, such as a library migration), or `cancelled` (the work was dropped). Only `confirmed` and `jira-only` claims must be assigned to a page. `claims.json` may also carry `factsWithoutClaims`: a list of `{ "id": "F123", "reason": "..." }` for customer-visible facts in a claimed feature that no ticket mentions. They are still documented; the list only shows where Jira is silent.
- `differences`: optional list of strings, one per detail in the ticket that the code contradicts, even when the claim is `confirmed`. The report lists them so a writer sees where the ticket and the product disagree. The code wins.
- The ticket is a claim. Never write a ticket key or customer name on a page.

## manifest.json (the plan the writer approves)

```json
{
"product": "pingcastle", "version": "3.6", "from": "3.5",
"pages": [
{ "path": "docs/pingcastle/3.6/administration/scan-options.md", "action": "UPDATE",
"type": "reference", "zone": "administration", "sidebar_position": 440,
"facts": ["F012"], "claims": ["C003"], "note": "" }
],
"dropped": [ { "id": "F077", "reason": "Covered by the KB, not the guide" } ]
}
```

- `path` is never under a `kb/` folder; the validator rejects it.
- `action`: `KEEP`, `UPDATE`, `REWRITE`, `RETIRE`, or `NEW`. Restyle is a separate pass after the doc-set, not an action.
- `type`: `task`, `concept`, `reference`, or `troubleshooting` (`.claude/references/page-structure-guide.md`). Not needed for KEEP or RETIRE.
- `zone` and `sidebar_position` follow `.claude/references/documentation-section-guide.md`.
- UPDATE, REWRITE, and NEW pages must list at least one fact.
- Every non-internal, non-removed fact is assigned to a page or listed in `dropped` with a reason. Every claim that isn't `contradicted` or `not-shipped` is the same.
- `renamedFrom`: set when a page keeps its content but changes path; the old file is removed from the new version folder and inbound links are updated at assembly.
- A move, split, or merge goes in `note` and needs the writer's yes before drafting.

## results/<batch>.json (written by draft agents)

```json
{ "batch": "administration",
"pages": [
{ "path": "docs/pingcastle/3.6/administration/scan-options.md", "status": "done",
"factsCovered": ["F012"], "todos": ["Default timeout not found in code"],
"untraced": [], "preexistingFindings": 0, "checks": { "quality": "pass", "integrity": "n/a" } }
] }
```

- `status`: `done` or `failed`. A page is done only when `quality:check` passes on the lines the draft wrote or changed.
- `factsCovered`: the fact ids the final page states.
- `preexistingFindings`: always 0. A drafter does not reword old text to clear a style finding; style work on old text is the separate restyle pass. A page is `done` only when the check passes on the lines the draft wrote or changed.
- `untraced`: sentences the verifier could not trace to a fact. Fix them or turn them into TODOs; the list must be empty for `done`.
57 changes: 57 additions & 0 deletions .claude/skills/doc-set/references/lint-pass.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Lint-only pass for KEEP pages

A KEEP page keeps its facts, structure, and wording. Use this pass only on a KEEP page that fails the commit's own style check, which runs in diff mode and looks only at the lines a change adds or rewrites (`npm run quality:check -- --only <list>`). A whole-page check (`--files`, `--file`) reports old wording too: in the Threat Manager 3.4 pilot it failed 62 of 72 KEEP pages with 142 findings, mostly passive voice. Those whole-page findings are for the report and the separate restyle pass, not for this pass. The lint-only pass fixes what the commit check fails and nothing else.

This pass fixes KEEP pages. It does not replace the final check: every run ends by linting ALL the version's pages, kept pages included (`SKILL.md`, Phase 9, "Lint every page", and `scripts/doc-set/lint-all.mjs`).

## Procedure

1. From the docs worktree, run `npm run quality:check -- --only <run-dir>/lintpass/all-keep.txt` (diff mode, or a smaller list). If every page passes, stop.
2. `node scripts/doc-set/lint-batches.mjs <run-dir>` splits the KEEP pages into batches of up to 15 (`lintpass/batch-N.txt`).
3. Launch one agent per batch, in parallel, with the prompt below. Each takes 30 to 65 minutes because the model-based check is slow.
4. `node scripts/doc-set/lint-batches.mjs <run-dir> --summary` totals the results. The agents' before and after counts are estimates, because Dale flags different sentences between runs.
5. Run the check on all KEEP pages again for the real count. Report it.
6. Show the writer what is left (below) and ask them to confirm the typo list in one batch. Apply confirmed typo fixes in a second pass, then recheck.

## Agent prompt

Give each agent these instructions, filling in the batch number and paths.

> You are doing a lint-only pass on pages of the <product> <version> docs that are otherwise unchanged from <previous version> (in an align run: unchanged from origin/dev). The content is the source of truth and must not change; you only reword sentences that the style check flags. Read `.claude/skills/doc-restyle/SKILL.md` (the sections "The original is the source of truth" and "Typos and wording errors"), `.claude/skills/doc-draft/style-reference.md`, and `.claude/references/lint-rules.md`.
>
> Work in the docs worktree <docsWorktree> (cd there; never edit files in the main checkout). Your pages are listed in `<run-dir>/lintpass/batch-N.txt`. `<seedBaseline>` is the commit in `meta.json` that holds the seeded pages; it is the baseline for the integrity check. In an align run there is no seed: use `oldRef` from `meta.json` (the `origin/dev` commit) in its place.
>
> For each page: (1) Run `npm run quality:check -- --file <page>` from the worktree. If it passes, leave the page untouched. (2) For each finding, reword only the flagged sentence, minimally: spell out an acronym on first use only when the page or its neighbours give the expansion, shorten a wordy phrase, replace a positional reference with a link or a name, and make a passive sentence active only under the voice rules below. Keep every fact, number, condition, qualifier, and warning. Code blocks, inline code, link targets, image paths, bold labels, quoted product messages, and admonitions stay exactly as they are. Follow the voice rules in this section, and never invent an actor. Never reword a bold label or quoted message to clear a finding. A Vale suppression is allowed only on text that must stay exactly as the product shows it; list each one. (3) Re-run the check, at most 3 rounds per page. Then run `node <repo>/scripts/doc-restyle/integrity.mjs --base <seedBaseline> <page>` (the commit recorded in `meta.json`) from the worktree. It fails when a code block, inline code, link or image target, bold label, number, or admonition changed. Undo the offending edit; never work around a violation. (4) If you see what looks like a typo or an obvious wording error, do not fix it. List it with the line number and your suggested fix.
>
> Edit only your batch's pages. Don't commit or stage anything. Write `<run-dir>/lintpass/result-N.json` and return a short summary.

## Voice rules

Use active voice where it is accurate. These rules decide what "accurate" means:

- **Procedures** are commands: "Click **Save**." Do not add "you" to a step.
- **Possibilities** depend on who can do the thing. When it is about what the reader can do, use "you can": "You can assign a role to a user." When it is about what a tool can do, name the tool: "Threat Manager can send the report by email." Never write "you can" for something the tool does, and never turn "X can be configured" into "you can configure X" unless the reader is the one configuring it.
- **Statements about what the product does now** may name the product when the page already makes the actor clear: "Threat Manager sends the email."
- **Past or completed actions, and the states they leave, keep their passive form when no actor is stated.** "This was pre-created in the Credential Profiles page" must not become "You pre-created this": the reader may not have created it, and someone else may have. The same goes for "has been configured", "have been modified", "was added", "is assigned to", and "as supplied when it was added".
- Never add "you", "someone", or the product as the actor of a past or completed action to clear a finding. If a sentence of this kind is flagged, leave it as written and list it under `unfixed` with the reason "past or completed action, actor not stated". The writer decides.
- A passive that only shortens harmlessly is fine to change ("objects that were deleted" to "objects deleted"), because it names no new actor.

## Result file

```json
{ "batch": 1,
"pages": [ { "path": "docs/<product>/<version>/<page>.md", "before": 4, "after": 0,
"integrity": "pass", "suppressions": [], "unfixed": [ "line 79: sentence and why" ] } ],
"typos": [ "path:line: suspected error and fix" ] }
```

## What is left, and why

Present these four groups to the writer, not a list per page:

- **Sentences inside admonitions.** The integrity check guards admonitions, so the agent can't reword them. The writer can reword them or accept the finding.
- **Undefined acronyms.** An agent may not invent an expansion. The writer or the code supplies it.
- **Typos that block a fix.** For example, rewording "threats generated by it's members" would also fix "it's". Agents list typos and don't fix them. Ask the writer to confirm the whole list at once.
- **False positives and unstable flags.** Dale sometimes flags a sentence that is already active, or flags different sentences on each run. After a final recheck, list what remains and let the writer decide to accept it.

A page with no frontmatter in the previous version may need a `title` and `description` added because lint requires a description. Tell the writer.
Loading
Loading