ADR-390: Author document-concision-pass skill - #239
Conversation
New, standalone, document-type-agnostic Wrapper-tier skill: given a file path, re-reads a document section by section and tightens its prose (cutting restated context, redundant hedging, and multi-sentence explanations) without dropping any decision, requirement, or scenario. Wiring it into proposal-first-draft, detailed-design-first-draft, dev-spec-first-draft, write-proposal, write-detailed-design, and write-dev-spec is explicitly out of scope (Task 2/ADR-387, Task 7/ADR-392).
build-and-test: Python test resultsStatus: ✅ Passed Test log |
jodavis-claude
left a comment
There was a problem hiding this comment.
Reviewed ADR-390: authoring document-concision-pass.
Requirements check:
plugins/dev-team/skills/document-concision-pass/SKILL.mdexists, takes a file path argument (viaargument-hint: <path to document>) — met.- No template assumption — explicitly stated in the intro paragraph — met.
- Validate step — performed manually (documented in the Implementation Summary), consistent with this feature's Wrapper-tier, no-automated-harness convention — met.
Structural conformance: follows document-discussion/document-readiness-review as the structural template (frontmatter shape, "Use this skill when..." intro, numbered ## Steps) as directed by the task brief.
One issue below worth addressing before merge (or explicitly deferring with a note, if the team decides it's out of scope for this task).
Uh oh!
There was an error while loading. Please reload this page.
document-concision-pass step 2 must not tighten > [!NOTE] / > **Method:** or > **Review:** blockquote blocks, since their exact marker syntax is depended on by playbook-contract's grep-based/agent recognition and document-discussion's own review workflow. Addresses PR #239 review comment.
jodavis-claude
left a comment
There was a problem hiding this comment.
Sign-off review for ADR-390 (document-concision-pass skill).
Prior thread check:
- Priority 4 (Documentation/design conformance) comment on step 2's missing carve-out for
> [!NOTE]/> **Method:**/> **Review:**blockquote blocks: addressed satisfactorily in commitf5aa7fd. The added carve-out correctly citesplaybook-contract's marker syntax and mirrorsdocument-discussion's existing wording; it's placed before the tightening steps (2b/2c) so it takes effect for every section. Resolved.
New issues in modified files: none. The fix commit only touches plugins/dev-team/skills/document-concision-pass/SKILL.md (7 lines added), scoped exactly to the requested carve-out, with no unrelated changes.
All prior threads are resolved and no new Priority 1-4 issues were found. Sign-off: approved.
document-concision-pass step 2 must not tighten > [!NOTE] / > **Method:** or > **Review:** blockquote blocks, since their exact marker syntax is depended on by playbook-contract's grep-based/agent recognition and document-discussion's own review workflow. Addresses PR #239 review comment.
Work item: ADR-390 — author
document-concision-pass, a new standalone, document-type-agnostic skill that takes a file path and tightens a document's prose section by section, without dropping any decision, requirement, or scenario.Changes:
plugins/dev-team/skills/document-concision-pass/SKILL.md(new) — a Wrapper-tier skill that re-reads a document section by section (heading-driven##blocks, falling back to#or nested###for long sections) and tightens prose (cutting restated context, redundant hedging, and multi-sentence explanations reducible to one sentence) while preserving every decision, requirement, and scenario. Makes no assumption about which template produced the file.proposal-first-draft,detailed-design-first-draft,dev-spec-first-draft,write-proposal,write-detailed-design, andwrite-dev-specis explicitly out of scope for this task and belongs to Task 2 (ADR-387) and Task 7 (ADR-392).Design decisions:
document-discussion/document-readiness-reviewas the structural template for a document-type-agnostic skill: a "Use this skill when..." intro plus a numbered## Stepssection operating purely off a document path.##blocks, falling back to#or a nested###block for long sections) — a reasonable interpretation consistent with the "without dropping any decision, requirement, or scenario" constraint. Flag for review if a different chunking approach was intended.Testing completed:
git show origin/dev/claude/ADR-388:_spec_ProposalDetailedDesignSplit.md, since that spec file is not yet present in this branch's ancestry). The sample tightened from ~330 words to ~190 words (~42% shorter) while every decision, requirement, and scenario in the original remained present, verified point-by-point.