ADR-387: Author proposal-first-draft and detailed-design-first-draft skills

[jodavis-claude]

Work item: ADR-387 — rename/rewrite design-first-draft into proposal-first-draft (repurposed for the Proposal-only document) and author a new detailed-design-first-draft skill, so the two sibling document-authoring skills stay stylistically consistent.

Changes:

• plugins/dev-team/skills/design-first-draft/ renamed to plugins/dev-team/skills/proposal-first-draft/ (git mv, assets/proposal_template.md moved unchanged) so the directory name matches the skill's name: field.
• plugins/dev-team/skills/proposal-first-draft/SKILL.md: name: changed to proposal-first-draft; step 1 rewritten from batched AskUserQuestion gathering to a section-by-section conversational interview (open question -> free-form follow-ups -> trade-off challenge with pros/cons -> Background-is-fact exception); added a new "Revising an existing document" step; tightened the TBD/Open-Questions language to require explicit user sign-off before anything is left open; added a document-concision-pass call as the final action of drafting, before the pause-for-review step; fixed the stale "Risks & Open Questions" wording to "Open Questions".
• plugins/dev-team/skills/detailed-design-first-draft/SKILL.md (new): authored against the pre-existing assets/detailed_design_template.md. Reads the approved Proposal in full as its first input; resolves _design_<Feature>.md's location/naming via the write-repo-documentation skill's documentation.specs placement (PascalCase); runs the same section-by-section interview style, Revising step, and TBD sign-off rule as proposal-first-draft; explicitly leaves ## Deliverables as a placeholder for design-deliverable-breakdown; ends with a document-concision-pass call.

Design decisions:

• Placed the document-concision-pass call as the last action inside the "Write the first draft" step (immediately before the pause-for-review step) rather than as its own separate numbered step, since the brief described it as "the last step of drafting" rather than a distinct pipeline stage.
• Positioned "Revising an existing document" as step 2, between "Gather context" (step 1) and "Write the first draft" (step 3), in both skills, keeping the two skills structurally identical (same step count and order).
• Did not restate each template section's own opening question inline in SKILL.md — both skills reference "each section's own opening question from the template" instead, to avoid the template files and SKILL.md files drifting out of sync.
• Left plugins/dev-team/skills/dev-spec-first-draft/SKILL.md, plugins/dev-team/skills/write-repo-documentation/SKILL.md, and plugins/dev-team/skills/use-context-file/assets/context_template.md untouched, per the brief's explicit read-only-reference notes — their own stale references or changes belong to other tasks.
• Validate checkbox left unchecked: this task's declared dependencies (Task 1/ADR-386 and Task 5/ADR-390, i.e. an ADR-380 Proposal-shaped source and the document-concision-pass skill) do not exist in the repo yet, so the manual Validate step (invoking both skills end-to-end) could not be run. The authoring work itself is complete and self-consistent.

Testing completed: Both proposal-first-draft and detailed-design-first-draft are Wrapper-tier prompt/config skills (per the spec's Component Breakdown) with no dedicated automated tests. Verified via grep that no stale design-first-draft/"Risks & Open Questions" references remain and that both template links resolve to existing files. No Gherkin/E2E harness exists in this repo to exercise these skills against.

[jodavis-claude]

Reviewed the ADR-387 diff against the task brief's exit criteria and CONTRIBUTING.md.

Summary of what was checked:

• skills/design-first-draft/ was removed via a real git mv (not just prose relabeling); proposal-first-draft/SKILL.md + assets/proposal_template.md exist with name: proposal-first-draft.
• detailed-design-first-draft/SKILL.md (new) exists with name: detailed-design-first-draft, alongside the pre-existing assets/detailed_design_template.md.
• Both skills' Step 1 is a section-by-section conversational interview (open question → free-form follow-up → trade-off challenge with pros/cons → Background-is-fact exception), worded consistently between the two files.
• Both have a "Revising an existing document" step (step 2) ahead of "Write the first draft" (step 3).
• TBD/Open-Questions language in both requires explicit user sign-off before anything is left open, and instructs going back through the interview rather than deferring silently.
• Both end their drafting step with a document-concision-pass call before the pause-for-review step.
• proposal-first-draft has no remaining "Behavior"/"Deliverables"/"Risks & Open Questions" section references (verified via grep) — the trimmed section set matches assets/proposal_template.md.
• detailed-design-first-draft resolves _design_<Feature>.md's location via write-repo-documentation's documentation.specs placement, consistent with that skill's actual behavior.
• Confirmed via repo-wide grep that other files still referencing design-first-draft by name (write-repo-documentation, get-project-configuration, add-to-spec.md, write-design-spec.md, design-deliverable-breakdown/SKILL.md, README.md) are all explicitly assigned to other tasks in _spec_ProposalDetailedDesignSplit.md (Tasks 6, 9, 10), not this task's scope — no unowned dangling reference was introduced.
• The Validate checkbox is correctly left unchecked; its own declared dependencies (ADR-386, ADR-390) don't exist yet in the repo, and the summary explains this rather than fabricating a stand-in.

This is a documentation/prompt-only (Wrapper-tier) change with no runtime code, so most of the standard priority list (fault tolerance, security, performance) doesn't apply. No Priority 1-4 issues found. Nicely self-consistent between the two sibling skills.

[jodavis-claude]

Review Summary

✅ Status: Approved

This PR successfully implements the split of design-first-draft into two focused skills:

Changes verified:

• plugins/dev-team/skills/design-first-draft/ renamed to proposal-first-draft/ with directory matching the name: frontmatter
• plugins/dev-team/skills/detailed-design-first-draft/SKILL.md newly authored against the pre-existing template
• Both skills implement consistent section-by-section conversational interview pattern
• Both include the "Revising an existing document" step and explicit TBD sign-off rule
• Both end with document-concision-pass call as intended
• No stale "Behavior"/"Deliverables"/"Risks & Open Questions" references remain in proposal-first-draft
• No unowned dangling references introduced elsewhere in the codebase

No Priority 1-4 issues found. Clean, self-contained Wrapper-tier prompt/config work. The Validate exit criteria checkpoint is appropriately marked incomplete pending dependencies (ADR-386, ADR-390).

[jodavis-claude]

Sign-off review

No unresolved review threads exist on this PR — the prior review pass (2026-08-11T06:07:15Z) approved the change with no inline comments, and no commits have landed since (the two authoring commits, 128c572 and 21e41ed, both predate that review). There is nothing new to scan.

Re-confirmed the substance of the prior approval by re-reading both proposal-first-draft/SKILL.md and detailed-design-first-draft/SKILL.md:

• Directory rename (design-first-draft → proposal-first-draft) is a real git mv; directory name matches name: frontmatter.
• Both skills implement the section-by-section conversational interview (open question → free-form follow-ups → trade-off challenge with pros/cons → Background-is-fact exception) identically.
• Both have a "Revising an existing document" step and the explicit-sign-off TBD/Open-Questions rule (no silent > TBD).
• Both end drafting with a document-concision-pass call before pausing for review.
• detailed-design-first-draft resolves _design_<Feature>.md location via write-repo-documentation's documentation.specs placement, and correctly leaves ## Deliverables as a placeholder for design-deliverable-breakdown.
• No stale "Behavior"/"Deliverables"/"Risks & Open Questions" references remain in proposal-first-draft.
• Validate exit-criteria checkbox is correctly left unchecked, with the dependency gap (ADR-386, ADR-390 not yet in repo) explained rather than worked around.

No new Priority 1-4 issues found. Signing off.

[jodavis-claude]

Sign-off complete and approved. Ready for handoff to the implementation team.

[github-actions]

build-and-test: Python test results

Status: ✅ Passed

Test log

[jodavis]

We shouldn't be hard-coding file name patterns anywhere. These need to come from Project settings.

[jodavis]

Does it make sense to have the first draft and revising skills both in the same skill? I'm asking because I'm not sure which is right. I don't want to duplicate instructions of there's overlap, but at the same time it seems like all of step 1 ignores the fact that there could be a while existing document to work from.

[jodavis]

Since the "user interview" is so similar between this and the detailed design, should it be split out into its own skill?

[jodavis]

Same question about revising vs first draft. Did it make sense these are the same skill?