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

[jodavis]

This line says "you are writing a complete new Proposal document" but step 3 looks for an existing proposal document. If this command is intended to work both for new documents and revising existing documents, it should be clearer up front.

The same comment applies to the corresponding language in write-detailed-design.md