ADR-392: Author write-proposal and write-detailed-design commands as a matched handoff pair

[jodavis-claude]

Work item

ADR-392 — Author the write-proposal command (rewritten from write-design-spec, moved via
git mv) and the new write-detailed-design command together, as a matched handoff pair, so a
user can run /write-proposal through to a finalized Proposal and either chain straight into
/write-detailed-design in the same turn or resume it later.

Changes

• plugins/dev-team/commands/write-design-spec.md → deleted via git mv to
  plugins/dev-team/commands/write-proposal.md, then rewritten in full: drops the
  deliverable-breakdown/work-item-creation steps (moved to write-detailed-design), adds a
  re-entrancy check before drafting (flexible source-resolution, since Proposals aren't
  config-tracked), and replaces the old "hand off to next command" ending with an
  AskUserQuestion chain-offer into write-detailed-design.
• plugins/dev-team/commands/write-detailed-design.md — new file. Resolves its Proposal
  input (in-hand if chained from write-proposal, otherwise via gather-brief-sources, with a
  hard stop and pointer to /write-proposal if none is found) → re-entrancy check via
  documentation.specs.search → detailed-design-first-draft → document-discussion →
  document-readiness-review with researcher-detailed-design-review →
  design-deliverable-breakdown → a second document-readiness-review pass on the breakdown →
  source-work-item-sync → document-concision-pass → hand-off telling the user to run
  /write-dev-spec <deliverable-id>.

Committed as two commits (one per Wrapper component, per Components-in-scope order):
write-detailed-design first (also carries the git mv), then the write-proposal rewrite.

Design decisions

• Both components are tier Wrapper per the spec's Component Breakdown (no executable logic,
  entirely prompt/config content) — implemented directly, no dedicated unit tests, consistent
  with every sibling command/skill in this pipeline.
• write-proposal's re-entrancy check is a direct question to the user (no automated search),
  since Proposals are deliberately not part of the documentation config schema.
• No design-create-work-items call was added to write-detailed-design — neither the spec's
  Component Breakdown nor its Planned Implementation prose for this task names that skill. This
  is a known open question surfaced for the spec author (see Known ambiguities below), not
  silently resolved.
• work-item-id derivation for a cold-started write-detailed-design (bare proposal-file-path,
  no work-item-id) skips the re-entrancy documentation.specs.search gracefully and lets
  source-work-item-sync fall through to its own "no source item" default.

Known ambiguities (surfaced, not resolved)

• Who creates the tracked feature-work-item per deliverable (the old write-design-spec.md had
  an explicit design-create-work-items step) is not named anywhere in this task's spec content,
  yet write-detailed-design's hand-off wording presupposes a real tracked ID exists. Needs
  confirmation with the spec author.
• This task's base branch (dev/claude/ADR-391) reflects the furthest-along of this task's five
  declared dependencies (ADR-387–391) in document order, per the stack anchor algorithm. Because
  ADR-390 and ADR-391 are separate, non-linear branches off the epic's feature branch (rather than
  one continuous chain), this PR's diff also carries ADR-390's document-concision-pass skill
  content until that branch's own PR merges upstream of this one.

Testing completed

No dedicated unit or E2E tests — both components are Wrapper tier (thin prompt/orchestration
content, no executable logic), consistent with the spec's Component taxonomy and every prior
task in this spec. Verified via structural review: every skill referenced by both new commands
(gather-brief-sources, identify-project-work-items, proposal-first-draft,
detailed-design-first-draft, document-discussion, document-readiness-review,
researcher-proposal-review, researcher-detailed-design-review, design-deliverable-breakdown,
source-work-item-sync, document-concision-pass) exists on this branch with the argument shape
each command assumes. A full live dry run against ADR-380 (per the spec's exit criteria) was not
executed, since it requires simulating a real human's answers across two full conversational
document-drafting interviews — recommended as a follow-up validation step.

[jodavis-claude]

Reviewed ADR-392's own two commits (35b8a7f, 60b1cb6) against the task brief's exit criteria, _spec_ProposalDetailedDesignSplit.md, and CONTRIBUTING.md. (Note: gh pr diff on this stacked PR also shows ADR-390/391 content because origin/dev/claude/ADR-391 — this PR's base — is a stale SHA of already-reviewed, content-identical commits; I scoped this review to ADR-392's actual diff, verified via git diff deaaac5..60b1cb6.)

Verified against exit criteria:

• write-design-spec.md removed via git mv; write-proposal.md and write-detailed-design.md exist and are invocable, argument-hints match the spec exactly.
• write-detailed-design hard-stops with no proposal found, pointing to /write-proposal (step 1).
• Both commands' re-entrancy checks precede drafting (write-proposal step 3, write-detailed-design step 2).
• write-proposal's final AskUserQuestion chain-offer (step 9) matches the spec's Planned Implementation wording closely, and correctly passes proposal path/work-item-id/related-items into write-detailed-design.
• All referenced skills (gather-brief-sources, detailed-design-first-draft, proposal-first-draft, document-readiness-review, researcher-proposal-review, researcher-detailed-design-review, design-deliverable-breakdown, source-work-item-sync, document-concision-pass) exist on this branch with argument shapes matching how each command calls them.
• The literal end-to-end "Validate" dry-run against ADR-380 was not executed live (it requires simulating a real human's answers across two full conversational interviews) — the developer did a structural verification instead and documented this transparently in Known Ambiguities. Consistent with the precedent set on the ADR-391 review for the same kind of infeasible-to-automate validation step; not treating this as blocking.

One substantive issue found — see inline comment on write-detailed-design.md.

No other Priority 1-4 issues found. Style is consistent with sibling commands (write-dev-spec.md), frontmatter shape matches, no stale write-design-spec/design-first-draft/researcher-design-review/design-work-items references in either new file.

[jodavis-claude]

Reviewed ADR-392's own two commits (35b8a7f, 60b1cb6) against the task brief's exit criteria, _spec_ProposalDetailedDesignSplit.md, and CONTRIBUTING.md. (Note: gh pr diff on this stacked PR also shows ADR-390/391 content because origin/dev/claude/ADR-391 — this PR's base — is a stale SHA of already-reviewed, content-identical commits; I scoped this review to ADR-392's actual diff, verified via git diff deaaac5..60b1cb6.)

Verified against exit criteria:

• write-design-spec.md removed via git mv; write-proposal.md and write-detailed-design.md exist and are invocable, argument-hints match the spec exactly.
• write-detailed-design hard-stops with no proposal found, pointing to /write-proposal (step 1).
• Both commands' re-entrancy checks precede drafting (write-proposal step 3, write-detailed-design step 2).
• write-proposal's final AskUserQuestion chain-offer (step 9) matches the spec's Planned Implementation wording closely, and correctly passes proposal path/work-item-id/related-items into write-detailed-design.
• All referenced skills (gather-brief-sources, detailed-design-first-draft, proposal-first-draft, document-readiness-review, researcher-proposal-review, researcher-detailed-design-review, design-deliverable-breakdown, source-work-item-sync, document-concision-pass) exist on this branch with argument shapes matching how each command calls them.
• The literal end-to-end "Validate" dry-run against ADR-380 was not executed live (it requires simulating a real human's answers across two full conversational interviews) — the developer did a structural verification instead and documented this transparently in Known Ambiguities. Consistent with the precedent set on the ADR-391 review for the same kind of infeasible-to-automate validation step; not treating this as blocking.

One substantive issue found — see inline comment on write-detailed-design.md.

No other Priority 1-4 issues found. Style is consistent with sibling commands (write-dev-spec.md), frontmatter shape matches, no stale write-design-spec/design-first-draft/researcher-design-review/design-work-items references in either new file.

[jodavis-claude]

Sign-off review for ADR-392.

Prior review thread (2 duplicate threads on write-detailed-design.md, same issue): Not addressed. No commits have landed on this branch since the review comments were posted (both ADR-392 commits predate them by ~15 minutes). The frontmatter description, the intro paragraph ('Once each deliverable has a feature-work-item...'), and step 10's hand-off text in write-detailed-design.md still claim a tracked feature-work-item exists per deliverable, but no step in the flow creates one. Per the task brief this is a known, surfaced ambiguity (not something the developer should resolve unilaterally), so it is not blocking sign-off on its own — but the wording itself should be corrected to be accurate today, or the spec author's decision obtained. Leaving both threads unresolved with follow-up replies.

New issues in modified files: None found. Both write-proposal.md and write-detailed-design.md otherwise match the task brief's exit criteria and key design decisions: re-entrancy checks precede drafting in both commands, the hard-stop-with-no-proposal path is correctly implemented, the chain-offer AskUserQuestion wording matches the spec near-verbatim and correctly invokes write-detailed-design in-line, and the cold-start work-item-id ambiguity (#3) is handled per the brief's recommendation (skip the re-entrancy search gracefully).

Decision: changes_requested — the prior review thread's issue remains unaddressed.

[jodavis-claude]

Sign-off review — ADR-392

Both duplicate review threads on plugins/dev-team/commands/write-detailed-design.md are now resolved: commit 58575c9 correctly reworded all three flagged spots (frontmatter description, intro paragraph, step 10 hand-off text) to state the precondition ("record each deliverable as a tracked work item") instead of asserting a feature-work-item already exists. Verified against the current file content — the fix is precise and consistent across all three locations, and does not unilaterally resolve the open Known Ambiguity #2 (whether write-detailed-design should call a work-item-creation step), correctly leaving that for the spec author.

Scanned the only file modified since the last review pass (write-detailed-design.md, diff 60b1cb6..58575c9) for new issues: none found. Both command files remain Wrapper-tier prompt/config content with no executable logic, so Priority 1-3 (correctness/fault-tolerance, security, performance) criteria don't apply. No documentation drift introduced.

Decision: approved.

[github-actions]

build-and-test: Python test results

Status: ✅ Passed

Test log