Skip to content

feat(01KW5W17): writeRetroProposal tool description matches the schema's accepted proposal types (#404)#452

Merged
jackmcintyre merged 1 commit into
mainfrom
story/native-01kw5w173m53fmzg7dawpr121q-writeretroproposal-tool-description-matc
Jun 29, 2026
Merged

feat(01KW5W17): writeRetroProposal tool description matches the schema's accepted proposal types (#404)#452
jackmcintyre merged 1 commit into
mainfrom
story/native-01kw5w173m53fmzg7dawpr121q-writeretroproposal-tool-description-matc

Conversation

@jackmcintyre

Copy link
Copy Markdown
Owner

What changed

writeRetroProposal tool description matches the schema's accepted proposal types (#404)

This change delivers the following acceptance criteria:

  • AC1: Given the writeRetroProposal tool description and JSDoc, When they are rendered, Then they list exactly the types in RETRO_PROPOSAL_TYPES, derived from the constant rather than a hardcoded count.
  • AC2: Given every proposal type in RETRO_PROPOSAL_TYPES, When it is round-tripped through the schema validator, Then each type validates successfully - including the types added since the original seven.

Why

As a retro-analyst, I want the writeRetroProposal description to enumerate every proposal type the schema actually accepts, so that the contract is not misread as silently dropping newer types (persona-append, lesson-consolidation, shared-skill-promotion, etc.).

How to check it yourself

  1. Open plugins/flow/mcp-server/src/tools/register.ts and find the writeRetroProposal registerTool call; confirm its description is now the WRITE_RETRO_PROPOSAL_DESCRIPTION constant, not a hardcoded string.
  2. Open plugins/flow/mcp-server/src/tools/write-retro-proposal.ts and read WRITE_RETRO_PROPOSAL_DESCRIPTION; confirm it interpolates RETRO_PROPOSAL_TYPES.length and RETRO_PROPOSAL_TYPES.join(", ").
  3. From plugins/flow/mcp-server run: npx vitest run src/tools/tests/write-retro-proposal.test.ts
  4. As the reviewer (the end-user check), read the rendered description that the test asserts: it lists all 13 types (rule … shared-skill-promotion) with no "seven types" phrasing, and the AC2 cases show every RETRO_PROPOSAL_TYPES entry validating through parseRetroProposalFile. Confirm all tests pass.

Risk and blast radius

Risk tier: medium

The change is scoped to the files in the diff below. Review the diff to judge its actual blast radius — including any effect on shared state, data schemas, or authentication paths — before approving.

What is explicitly not covered: reviewer verification of this summary's accuracy is handled by a separate companion story.

Evidence

The pre-pull-request build-and-test gate passed before this pull request was opened. No pull request can be opened by the automated flow unless both pnpm build and pnpm test exit 0 in the developer's working directory.

Per-criterion covering checks:

  • AC1 → plugins/flow/mcp-server/src/tools/__tests__/write-retro-proposal.test.ts (automated test)
  • AC2 → plugins/flow/mcp-server/src/tools/__tests__/write-retro-proposal.test.ts (automated test)

Story: native:01KW5W173M53FMZG7DAWPR121Q
Spec: .flow/native-stories/01KW5W173M53FMZG7DAWPR121Q.md
ACs:

  • AC1: Given the writeRetroProposal tool description and JSDoc, When they are rendered, Then they list exactly the types in RETRO_PROPOSAL_TYPES, derived from the constant rather than a hardcoded count.
  • AC2: Given every proposal type in RETRO_PROPOSAL_TYPES, When it is round-tripped through the schema validator, Then each type validates successfully - including the types added since the original seven.

Derive the writeRetroProposal tool description from RETRO_PROPOSAL_TYPES so it enumerates every accepted proposal type instead of a stale hardcoded seven

Closes #404

…a's accepted proposal types (#404)

The writeRetroProposal tool description (register.ts) and module JSDoc
said the proposal schema accepts seven types and listed only the
original seven, but RETRO_PROPOSAL_TYPES has grown to thirteen
(persona-append, promote-lesson-to-skill, build-story,
lesson-consolidation, lesson-retirement, shared-skill-promotion, etc.).
The contract was being misread as silently dropping newer types. This
exports a WRITE_RETRO_PROPOSAL_DESCRIPTION constant built by
interpolating RETRO_PROPOSAL_TYPES (both the count and the enumerated
list) so the description can never drift from the schema again, wires
register.ts to use it, refreshes the stale JSDoc/comments in
write-retro-proposal.ts and retro-proposal.ts, and adds tests asserting
the description enumerates exactly RETRO_PROPOSAL_TYPES (AC1) and that
every type round-trips through parseRetroProposalFile (AC2). No runtime
acceptance behaviour changed — the schema already accepted all thirteen
types; this fixes stale documentation. Build green, dist rebuilt, full
suite (3861 tests) green.
@jackmcintyre jackmcintyre merged commit f0964f3 into main Jun 29, 2026
1 check passed
@jackmcintyre jackmcintyre deleted the story/native-01kw5w173m53fmzg7dawpr121q-writeretroproposal-tool-description-matc branch June 29, 2026 06:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[writeRetroProposal] Description says seven proposal types but eleven are accepted

1 participant