Skip to content

feat(doc-set): add the doc-set skill, workflow, and review-page tooling - #1823

Open
jth-nw wants to merge 20 commits into
devfrom
feat/doc-set-skill
Open

jth-nw wants to merge 20 commits into
devfrom
feat/doc-set-skill

Conversation

@jth-nw

@jth-nw jth-nw commented Nov 2, 2026

Copy link
Copy Markdown
Collaborator

Drafts or updates a whole documentation set for one product version from code, Jira, and existing docs, and builds a review page for the team: side-by-side rendered and Markdown views, votes, suggested edits, a dashboard, and a priority ranking (bands P1 to P4) so reviewers approve the pages that matter most first.

Drafts or updates a whole documentation set for one product version from code,
Jira, and existing docs, and builds a review page for the team: side-by-side
rendered and Markdown views, votes, suggested edits, a dashboard, and a
priority ranking (bands P1 to P4) so reviewers approve the pages that matter
most first.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Comment thread scripts/doc-set/review-client.js Fixed
Comment thread scripts/doc-set/review-client.js Fixed
Comment thread scripts/doc-set/seed-version.mjs Fixed
…oling

- review-client.js: copy only known, correctly typed keys from stored prefs
  (remote property injection) and build the review bar with DOM calls instead
  of innerHTML (DOM text as HTML).
- seed-version.mjs: escape the product id before it goes into a regular
  expression, and rewrite version-specific paths in the copied sidebar.
- review-html.mjs, author-report.mjs: treat a RESTYLE page as restyled instead
  of crashing the review page build, and take the old and new version labels
  from the run instead of hardcoding 3.3 and 3.4.
- review-package.mjs: add subresource integrity to the marked script.
- package.json: run scripts/test-doc-set.mjs in test:scripts.
- Tests for each fix.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
jth-nw and others added 9 commits November 5, 2026 16:16
A product with a single current version has no release to diff and no previous
folder to copy. Align mode checks every page against the code live in
production and edits the pages in place.

- align-init.mjs sets up the worktree and run state from origin/dev, and
  refuses a versioned product.
- docs-paths.mjs holds the shared path and old-text helpers. In an align run
  the old text is read from git at oldRef instead of a previous version folder.
- review-html, author-report, priority, review-package, and progress use the
  helpers, and no longer assume docs/<id>/<version>/.
- The skill, workflow, and references describe the mode: the deployed ref is
  named by the writer, never the tip of main; verified_ref in the product brief
  records the last aligned ref; work goes by zone with one PR per zone.
- Tests for the helpers, the git-based old text, align-init, and progress.
  Versioned runs are unchanged: the Threat Manager 3.4 page data and ranking
  are identical to before.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A stray apostrophe in the single-quoted whenToUse string stopped the Workflow
tool from loading doc-set.js. Reword it, and add a test that parses the script
the way the tool does (as the body of an async function), so a broken string
fails in CI.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…w page

review-package.mjs, review-html.mjs, and author-report.mjs wrote straight to
the output path and failed with ENOENT when its folder did not exist, which
is the case on the first run of a product. Create it first, and test a nested
output path.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
merge-facts.mjs numbered every fact from F001 in file order, so adding an area
that sorts earlier renumbered facts that manifests, results, and notes already
refer to. A fact that is still present (same area, cite, and statement) now
keeps its id, new facts continue after the highest id, and a dropped id is not
reused. Test included.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
merge-facts.mjs documented a dedupe.json override but never read it. Read
{"keep": [ids]} and never mark a listed fact as a duplicate or let it stand in
for another. Similar permission descriptions and delete prompts were being
merged as duplicates. Test included.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A slice file may carry newPages rows; triage-to-manifest.mjs turns them into
NEW pages in the manifest, and still reports a path that two slices claim.
Test included.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A KEEP page whose manifest row carries an unverifiable reason is left exactly
as it is and shown in its own section of the author report, with the reason,
instead of in the unchanged count. The section explains that doc-set checks
pages against code, so it could not confirm or correct them. Test included.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…d or changed

The verifier traced every factual sentence on a page to an assigned fact. An
align run edits pages in place and keeps most of an updated page, and the fact
pack never covers all of that old text, so every page failed on sentences the
draft had not touched. For a versionless run the verifier now checks only the
added or changed sentences (from git diff against oldRef) and flags an
unchanged sentence only when it contradicts an assigned fact.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
On a retry the draft prompt said to fix exactly the verifier's problems, and
drafters cleared 'sentence has no fact' by deleting sentences that were on the
page before the run. In an in-place update the rest of the page must stay. A
problem is now fixed by correcting the sentence or stating the missing fact; an
unbacked original sentence stays and is listed under todos.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Comment thread scripts/doc-set/align-init.mjs Fixed
Comment thread scripts/doc-set/align-init.mjs Fixed
jth-nw and others added 2 commits November 5, 2026 16:25
The final style check covered only the pages a run edited, and the skill did not
require it. Phase 9 now lints ALL the version's pages (new, rewritten, updated,
restyled, and kept pages), and a run is not finished until
lint-all.mjs --check confirms final-recheck.txt covers every page. A page the
writer told the run not to change is linted too: its findings go in the report
and the page stays as it is.

lint-all.mjs lists the pages (minus kb/ and CLAUDE.md files), prints the check
command, and with --check names any page the check missed. Test included.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ree of style rewording

doc-set is about writing missing pages, correcting existing pages for accuracy,
and rewriting a page when too much is wrong. Restyle is a second, separate pass
after the doc-set completes.

- RESTYLE is no longer an action: the manifest validator rejects it and points
  to the separate pass, and the workflow and skill drop the RESTYLE step.
- The draft step ran the style check on the whole page (--file), which pushed
  drafters to reword old sentences. It now runs in diff mode (--only), which
  looks only at the lines a run adds or changes, and says to leave old text
  byte-for-byte. preexistingFindings is always 0.
- The final lint of every page prints two commands: the whole-page report, and
  the commit check. Only findings on lines the run changed are fixed; findings
  on old text go to the report as candidates for the restyle pass.
- The skill gains an 'After the doc-set: the restyle pass' section: its own
  branch, commit, PR, and review, never mixed into doc-set pages.
- The review and report group for KEEP pages with only style-check wording is
  now 'Style fixes only' (P4 Style fixes only), not 'Restyled only'.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…the PR

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
jth-nw and others added 2 commits November 6, 2026 12:23
… commit-check counts

The author report's style-check section listed every failing page without saying
that a whole-page check also reports old text the doc-set does not reword. It now
says so, shows the commit check (changed lines only) result from
lintpass/commit-check.txt, and names failing pages as candidates for the separate
restyle pass. lint-all.mjs prints the command that writes that file.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ct pack

A run that finished without a brief left the fact extractors and triage agents
with no product context (legacy names, the code-to-docs map, pitfalls). Intake
now writes a missing brief first, from the repo's own ARCHITECTURE.md and
GLOSSARY.md and a code survey, shows it to the writer, waits for a yes, and
passes its path to every extractor and triage agent.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…sing latest, slug collisions

- seed-version.mjs: a new version keeps the previous latest entry's other keys
  (for example kb: false, which stops the build copying the Knowledge Base into a
  version that has none) and says which it carried over.
- Entry-point guard: comparing import.meta.url with file:// plus argv[1] is false
  on Windows and on paths with a space, so a script exited 0 and did nothing.
  is-main.mjs compares real paths, and 15 scripts use it.
- seed-version.mjs: when no version is marked isLatest and --from is not given, say
  so instead of throwing a TypeError.
- review-html.mjs and author-report.mjs: two pages whose paths become the same review
  id (a_b.md and a-b.md) are reported at build time instead of silently sharing
  an anchor, a template, and reviews.

Tests for each.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Code Review

No changes to docusaurus.config.js, products.js, sidebars, the KB copy pipeline, or the GitHub Actions workflows. The package.json change only adds node --test scripts/test-doc-set.mjs to test:scripts, which script-tests.yml already runs on scripts/ changes.

I found two issues, neither blocking.

1. .doc-set/ run state isn't gitignored (medium)
align-init.mjs and the skill write run state to <repo>/.doc-set/<product>-<version>/ in the main checkout. That folder holds facts.json, claims.json, Jira-derived claims, and meta.json with absolute local paths. .gitignore has no entry for it, so a git add -A or git add . on the main checkout would commit it. The drafting prompt explicitly keeps ticket keys, customer names, and internal facts off the pages, so this data shouldn't reach a public repo. Fix: add .doc-set/ to .gitignore.

2. seed-version.mjs doesn't validate --to (low)
addVersion() interpolates to straight into src/config/products.js (version: '${to}', sidebarFile: './sidebars/${id}/${to}.js') and into path.join(ROOT, docsPath, to). A typo such as --to "12.0'" or --to ../x with --apply writes a broken products.js, which breaks the whole build, or copies outside the product folder. The script only runs locally with input the writer controls, but a guard such as /^\d+(\.\d+)*$/.test(to) before the dry-run plan would catch it.

What I checked and found sound

  • Review page (review-client.js): the marked renderer escapes raw HTML, renders only http(s) links as anchors (with rel=noopener), and turns images into placeholders. The inlined JSON escapes <, U+2028, and U+2029, and </script is escaped in the inlined client. Other reviewers' suggestions go through the same escaping path. Values read back from localStorage are type-checked.
  • Subprocess calls: execFileSync with argument arrays, with no shell interpolation.
  • Pages lint-all.mjs and the workflow write: the quality:check flags they use (--files, --only, --progress) exist in scripts/quality/check.mjs. Base-mode change discovery includes untracked files, so newly seeded pages get checked.
  • Path handling: seed-version.mjs refuses to overwrite an existing target folder, and align-init.mjs refuses an existing worktree.

I couldn't run scripts/test-doc-set.mjs in this environment, so the tests are unverified here.

This branch was previously deployed

1 inactive deployment
development — e2d67c08 Deployed Nov 9, 2026 by jth-nw via build-and-deploy #5092
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants