Feature/adr 336 proposal detailed design split - #252
Merged
Merged
Conversation
* ADR-390: Author document-concision-pass skill 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). * ADR-390: Carve out Method/Review markers from concision pass 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. * ADR-390: Generalize callout-block carve-out to any single-word tag Replace the Method/Review-specific enumeration with a generic > **<Tag>:** pattern description, so a future callout type doesn't need its own carve-out added here. Also drops the "instead of the two originally-named markers" framing in favor of describing the current rule directly, per review feedback on writing skill prose for a first-time reader rather than as a diff against prior wording. --------- Co-authored-by: Claude on behlaf of jodavis <ElwoodMoves@hotmail.com>
…ev-spec pipeline (#244) * ADR-393: Add re-entrancy check and final concision pass to write-dev-spec Inserts a new step 2 that checks documentation.dev-specs.search for an existing dev spec and, if found, has step 3 invoke dev-spec-first-draft in revise mode instead of first-draft mode. Adds a final step 9 that runs document-concision-pass over the finished spec, for symmetry with write-proposal/write-detailed-design. Also brings in document-concision-pass/SKILL.md (authored on ADR-390's still-open branch) so this reference resolves to a real skill, per ADR-393's stated dependency on ADR-390. * ADR-393: Add revise mode, Contents-last note, tightened TBD language, and final concision pass to dev-spec-first-draft Inserts a new step 2 'Revising an existing document', mirroring proposal-first-draft/detailed-design-first-draft but adapted to this skill's existing batched-AskUserQuestion interaction style rather than a section-by-section interview rewrite. Step 3 (renumbered from step 2) now writes/regenerates the Contents section last, tightens the TBD/Open Questions language to require explicit user confirmation rather than a silent default, and ends with a document-concision-pass call. Also brings in the pre-authored assets/dev_spec_template.md (already linked by this file, but missing from this branch) from the still-open ADR-336 spec-authoring PR. * ADR-393: Address review comments on dev_spec_template.md and dev-spec-first-draft - dev_spec_template.md: stop hard-coding the _design_<FeatureName>.md / _doc_<FeatureName>.md naming patterns in the Design/Architecture doc header lines; describe them as resolved via documentation.specs / documentation.architecture instead, matching the ADR-387 precedent. - dev_spec_template.md: encourage Mermaid diagrams in Key Classes and Data Flow where they'd be clearer than prose. - dev-spec-first-draft/SKILL.md: rewrite from a "new or revising" perspective throughout instead of a separate bolted-on revising step, matching PR #171's structural pattern. Keeps the existing batched AskUserQuestion gathering style unchanged — adopting the section-by- section conversational interview is a separate, larger change the spec author is deferring. * ADR-393: Address follow-up review comments on dev-spec-first-draft - When revising, reuse the existing spec's ## Related Docs section instead of re-discovering architecture docs and spawning fresh research from scratch; only look further for gaps the new brief raises. Matches the same fix already applied to proposal-first-draft in PR #171. - Stop naming the _spec_<FeatureName>.md pattern explicitly in step 2; resolve the file's location and naming via write-repo-documentation's documentation.dev-specs placement instead, matching the pattern already applied to the template's own header lines and to detailed-design-first-draft in PR #171. --------- Co-authored-by: Claude on behlaf of jodavis <ElwoodMoves@hotmail.com>
#245) add-to-spec covered one narrow case (appending a bounded addition to an existing document) that the revise mode being added to write-proposal, write-detailed-design, and write-dev-spec elsewhere in this epic strictly subsumes. Bumps plugins/dev-team's plugin.json version (1.4.0 -> 1.4.1) per the plugin-version-check CI gate. Co-authored-by: Claude on behlaf of jodavis <ElwoodMoves@hotmail.com>
* Add ADR-336 dev spec and proposal/detailed-design/dev-spec templates Introduces the dev spec for the Proposal/Detailed Design split (ADR-336) along with the new document templates it defines: a proposal template for write-design-spec's first-draft skill, a detailed design template for the new detailed-design-first-draft skill, and a dev spec template for write-dev-spec's first-draft skill. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0173ECh95RcYr18Pa1CnLT2z * ADR-336: fix task heading/marker format in spec Rewrite the Tasks section headings to the [ADR-XXX: Title](url) 🤖/🧑 form and Depends-on lines to reference real ADR-XXX keys instead of local Task N numbers, so stack_registration.py can parse the stack order for tasks in this epic. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ta9LkHviRw9DHfj54wRtam --------- Co-authored-by: Claude on behlaf of jodavis <ElwoodMoves@hotmail.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
…skills (#171) * ADR-387: Rename design-first-draft to proposal-first-draft with section-by-section interview Renamed the skill directory and SKILL.md name field, replaced the batched AskUserQuestion gathering step with a section-by-section conversational interview (with the Background no-challenge exception), added a Revising an existing document step, tightened the TBD/Open Questions sign-off language, and replaced inline tightening with a document-concision-pass call. Fixed the stale 'Risks & Open Questions' reference to 'Open Questions'. * ADR-387: Author detailed-design-first-draft skill New skill authored against the already-existing assets/detailed_design_template.md. Reads the approved Proposal in full, resolves _design_<Feature>.md's location via write-repo-documentation's documentation.specs placement, runs the same section-by-section conversational interview style as proposal-first-draft (with the Background no-challenge exception), includes a Revising an existing document step, applies the same explicit-sign-off TBD rule, and ends with a document-concision-pass call. * ADR-387: Extract document-section-interview skill; rewrite for new-or-revising perspective Addresses PR #171 review comments: - Extracts the section-by-section interview logic (open question, follow-up, trade-off challenge, Background exception, TBD sign-off rule) that was duplicated near-verbatim between proposal-first-draft and detailed-design-first-draft into a shared document-section-interview skill. - Rewrites both skills to speak from a "new document or revision with new information" perspective from the intro onward, instead of bolting revise handling on as a separate step 2 after an implicitly new-only step 1. - Softens detailed-design-first-draft's description/step 3 to describe the save location as resolved via documentation.specs rather than naming the literal _design_<Feature>.md pattern, since the actual naming is config-driven, not hard-coded here. * ADR-387: Address follow-up review comments on document-section-interview and proposal-first-draft - document-section-interview: merge the two "Use this skill when" bullets into one, since revising vs. first-drafting a document via a first-draft skill were never mutually exclusive cases (the AND/OR reading was ambiguous). Also move the em-dash aside in step 1's revising sentence to the end instead of the middle, where it was breaking up "ask X rather than Y." - proposal-first-draft: when revising, reuse the existing Proposal's own `> **Source:**` line and `## Alternatives Considered` section instead of always researching from scratch; only spawn new research for gaps the new brief actually raises. * ADR-387: Apply revision-research-reuse guidance to detailed-design-first-draft too Same fix as proposal-first-draft's: when revising, reuse the existing document's prior research instead of re-running find-repo-documentation and spawning fresh researcher agents from scratch, only looking further for gaps the new brief raises. Detailed Design has no Alternatives Considered/Related Docs section to point at directly, so this phrases it as "the existing content already reflects" the prior research rather than citing a specific section. --------- Co-authored-by: Claude on behlaf of jodavis <ElwoodMoves@hotmail.com>
* ADR-388: Rename researcher-design-review to researcher-proposal-review, scoped to problem/solution-fit Drops deliverable-independence check and the success-criteria-observable / behavior-scenario-completeness bullets, which move to the new researcher-detailed-design-review skill. * ADR-388: Author researcher-detailed-design-review skill New skill checking user-scenario completeness, functional-requirements-table well-formedness, success-metric observability, and deliverable independence against the Detailed Design document's own sections. Covers the checks split off from the old researcher-design-review skill's steps 4-5 that don't belong to researcher-proposal-review's problem/solution-fit scope. * ADR-388: Apply review suggestions to independently-cuttable wording A deliverable can depend on an earlier deliverable shipping first; the disqualifying case is another deliverable needing to ship after it to provide value. Reword both bullets per the reviewer's suggested diffs. --------- Co-authored-by: Claude on behlaf of jodavis <ElwoodMoves@hotmail.com>
…lize it (#241) * ADR-389: Rename design-work-items to source-work-item-sync and generalize it Generalizes the skill to be callable after either write-proposal or write-detailed-design, summarizing whichever Proposal/Detailed Design doc(s) are finalized so far into the originating tracked source's description. Replace/Update dispatch semantics via work-tracking config are unchanged. * ADR-389: Remove stale extension-point-skill callout from source-work-item-sync This skill's whole process is already just reading get-project-configuration's work-tracking section and dispatching to it -- the full-file-override callout was leftover framing from before the config-driven rewrite, per review comment. --------- Co-authored-by: Claude on behlaf of jodavis <ElwoodMoves@hotmail.com>
…-draft in design-deliverable-breakdown/SKILL.md (#242) Reword 'design doc' to 'Detailed Design doc' in the frontmatter description, use-this-skill-when bullet, and both steps, matching detailed-design-first-draft/SKILL.md's established phrasing. Co-authored-by: Claude on behlaf of jodavis <ElwoodMoves@hotmail.com>
…a matched handoff pair (#247) * ADR-392: Author write-detailed-design command git mv commands/write-design-spec.md to write-proposal.md ahead of its own rewrite in the next commit. * ADR-392: Rewrite write-proposal command Repurposed from write-design-spec.md: drops deliverable-breakdown/work-item-creation steps (moved to write-detailed-design), adds a re-entrancy check and a final chain-offer into write-detailed-design. * ADR-392: Correct write-detailed-design.md wording to not claim work-item creation Frontmatter, intro paragraph, and step 10 hand-off text all asserted a tracked feature-work-item exists per deliverable, but no step in the command's flow creates one. Reworded all three spots to state the precondition (deliverable must be recorded as a tracked work item) without claiming this command performs that step, per review feedback on PR #247. Whether write-detailed-design should call a work-item-creation step remains an open question for the spec author (task brief Known Ambiguity #2), unresolved by this fix. * ADR-392: Address review comment on write-proposal/write-detailed-design intro wording Both commands' intro paragraphs said "writing a complete new" document even though each has a step that finds and revises an existing one. Reword both to state the new-or-revising duality up front. --------- Co-authored-by: Claude on behlaf of jodavis <ElwoodMoves@hotmail.com>
jodavis
enabled auto-merge
September 15, 2026 13:08
…sal-detailed-design-split # Conflicts: # plugins/dev-team/.claude-plugin/plugin.json # plugins/dev-team/commands/write-dev-spec.md
build-and-test: Python test resultsStatus: ✅ Passed Test log |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.