chore(skills): QA and trim the skill definitions; deliver opens a normal pull request

[sebastian-iancu]

Summary

A QA pass over the skill definitions, done with the plugin-dev skill-development checklist. It fixes the defects the pass found, trims the text that restated a reference, and changes /sdd-deliver to open a normal pull request.

Every skill passes the mechanical checks:

• name matches its directory;
• the description is third person, with four to seven quoted triggers;
• argument-hint and allowed-tools are present on every sdd-* skill;
• every cited file and section exists;
• there is no second person.

Four parallel skill reviews then judged the skills, references/review.md and the three reviewer agents. Every finding below was verified against the code or the reference before it was applied.

Fixed

• Paths. /.sdd/gate-…log and /.sdd/diff-…patch are gitignore notation; as shell paths they point at the filesystem root. They are now .sdd/.
• --since-last diffs. A --since-last review handed reviewers the whole branch's hunks: scope --diff was not given step 1's flags.
• Leftover pass notes. --panel, and a pass with nothing reported, left the pass note behind. record --reported 0/<m> now also removes the guard's scratch worktree.
• The review's drift check ran the plugin's gate instead of the vendored one (references/sdd-check.md).
• /sdd-triage --backlog did nothing with forge: none, because harvest refuses there.
• sdd-specify told agents to write status values into the requirement file. The map record owns them, and generate rewrites the file. Its trigger "document how this works" also matched any documentation request; it is now "write a knowledge-base page".
• sdd-scaffold skipped wiring the gate when a spec-check target already existed, against scaffold-upgrade.md §6. It also carried a copy of the upgrade order that had drifted.
• The router routed to three agents it cannot dispatch, and did not say to read the descriptor first.
• Contradictions in the reviewer agents:
  • the auditor's digest was written for a branch range;
  • pull's severity reading was misdocumented;
  • sdd-trace added audit lines to the findings file while being report-only.

Changed

• /sdd-deliver opens a pull request ready for review, a draft only when the maintainer asks for one.
  • The close-out runs when nothing blocks but a draft, and marks a draft ready.
  • The panel prompts print before the maintainer's review rather than after close-out.
  • A close-out after merge commits on the default branch or a branch from it.

Trimmed, then audited for lost meaning

The first pass cut too much. An independent audit compared every removed sentence with the reference it now cites:

• Restored, because they carried a rule, a definition or an example an agent needs:
  • the list of wrong code behaviours;
  • the branch-slug rule;
  • Next:'s values;
  • Azure DevOps' closed comment threads;
  • the doc reviewer's environment-keyword cap and its critical "two homes" rule;
  • "and n more";
  • the auditor's upstream rule;
  • code-first drift;
  • specify's full-lane and "DDL stays in the specs" notes.
• Reverted, because they had changed a rule:
  • the critical bullet's "the change touches";
  • "a cheap refactor" as a lead;
  • the conformance grading;
  • the scaffold's "don't force" wording;
  • record's refusal.
• Kept, because they close gaps rather than change behaviour:
  • review.md now lists the doc reviewer's two existing important cases (a binding change that skipped its lane or ADR);
  • the auditor's hand-checked families get a severity.

File	Before	After
references/review.md	2459	2162
sdd-review	1027	926
sdd-scaffold	1166	972
sdd-specify	884	778
sdd-deliver	1531	1449
sdd-trace	551	404
router	695	566
sdd-triage	906	933 (+ the forge: none path)
the three agents	2753	2463

Not taken: further trims of sdd-triage's steps, which would have cut the reasoning in "verify with surroundings", and dropping the reviewers' limit of ten suggestions.

Docs

The seven skills, references/review.md, the three reviewer agents, references/templates/ai-workflow.md and AGENTS.md, the README, AGENTS.md, docs/quick-start.md, docs/examples.md and the CHANGELOG.

Verification

• ./scripts/validate.sh: OK, budgets included; hooks-test: OK.
• python3 -m unittest discover -s tools/tests: 512 tests OK.
• claude plugin validate .: passed.

Notes for review

• Look hardest at sdd-deliver steps 8–10, the draft and close-out wording, and at references/review.md § Severity and § The tool.
• Release: together with feat: land the review-quality stack (#46, #47, #48) on main #49 this is 0.12.0. docs/upgrading.md still needs its 0.11.x → 0.12.0 section, which should also mention the non-draft pull request.

Checklist

• Scoped to one logical change
• The gates above pass locally and their output was read
• CHANGELOG entry under Unreleased, when the change is user-visible; version bumped per docs/versioning.md at release
• Both manifests kept in sync, and AGENTS.md, README.md, the Cursor rule and hooks/session-start.sh synced when components changed
• No internal or private repository names, absolute paths or organisation-private details; disclosure grep clean over the tree, CHANGELOG.md and this branch's commit messages

🤖 Generated with Claude Code