USM

Appearance

usm/gen-feature-review [planned] ​

Review-quality feature markdown — restructures the feature markdown generator to produce a spec document a human can read and approve, not a structural field dump. Optimises for the human review step in the spec-first workflow.

Status: planned

Intent ​

In the spec-first workflow, the agent writes a feature .usm spec, generates markdown, and the human reviews it before the agent builds. The current markdown generator produces structural reference docs — tables of fields, mechanical section ordering. A human reviewing a feature spec needs to quickly answer: What will be built? What are the steps? What must be true? How will it be tested? The current output doesn't frame these questions. This feature restructures the feature markdown to read like a reviewable spec.

Decisions ​

review-mode-separate-from-reference [accepted] ​

Decision: Add a review-oriented template alongside the existing overview template

Rationale: The existing overview.md is useful as a structural reference (what fields exist, where files are). The review template serves a different purpose: human approval before implementation. Keeping both lets the overview remain a reference while the review doc is the approval artifact.

flows-as-numbered-steps [accepted] ​

Decision: Render flows as numbered human-readable steps, not tables

Rationale: A table of {id, action, target} is hard to read as a narrative. Numbered steps like "1. Receive structured feature fields → 2. Validate against schema → 3. Generate YAML + markdown" read like a procedure a human can follow and approve.

contracts-as-checklist [accepted] ​

Decision: Render contracts as a markdown checklist the human can mentally tick

Rationale: Contracts are guarantees the implementation must satisfy. A checklist (- [ ] ...) frames them as acceptance criteria, which is how a human naturally reviews a spec: "does this cover what I expect?"

tests-as-given-when-then [accepted] ​

Decision: Render tests in given/when/then format

Rationale: The .usm test schema already has setup (given), implied action (when), and expect (then). Making this explicit in the markdown helps the human understand what test cases will verify the feature.

Flows ​

Generate review-quality markdown from feature .usm (generate-review-doc) ​

When a feature .usm is generated, produce a review.md alongside overview.md that frames the spec for human approval.

  1. parse → feature .usm file
  2. generate → review.md with intent, flows, contracts, tests sections
  3. write → .agents-workspace/docs/<area>/review.md

Render flows as numbered procedural steps (render-flows-as-prose) ​

Convert the flows[] array into readable numbered steps grouped by flow, with each step's action and target combined into a sentence.

  1. parse → flows array
  2. transform → each step into "N. {action} → {target}" format
  3. group → steps by flow with flow name as subheading

Render contracts as acceptance checklist (render-contracts-as-checklist) ​

Convert the contracts[] array into a markdown checklist under each contract description.

  1. parse → contracts array
  2. transform → each must_have item into "- [ ] {item}"
  3. group → under contract description as subheading

Render tests in given/when/then format (render-tests-as-bdd) ​

Convert the tests[] array into given/when/then blocks for readability.

  1. parse → tests array
  2. transform → setup → Given, flow ref → When, expect → Then
  3. format → each test as a block with bold Given/When/Then labels

Contracts ​

review-doc-has-approval-framing ​

The review.md must frame the spec for human approval

Acceptance criteria:

  • [ ] Starts with a one-line intent summary in plain language
  • [ ] Flows section reads as a procedure, not a data table
  • [ ] Contracts section is a checklist, not a table
  • [ ] Tests section uses given/when/then format
  • [ ] Ends with an implementation plan section (primary file, status)

review-doc-is-separate-from-overview ​

review.md is a new file, overview.md is unchanged

Acceptance criteria:

  • [ ] overview.md continues to be generated with current format
  • [ ] review.md is generated alongside overview.md
  • [ ] Both files share the same output directory

decisions-included-when-present ​

When a feature has decisions[], they appear in the review doc

Acceptance criteria:

  • [ ] Each decision shows the decision text and rationale
  • [ ] Decisions frame as 'Why this approach' section

Tests ​

review-doc-from-feature-with-all-fields ​

Given:

  • feature_with_flows_contracts_tests_decisions: true

Then:

  • assertion: review.md has Intent, Flows, Contracts, Tests, Decisions, Implementation sections
  • assertion: flows rendered as numbered steps not tables
  • assertion: contracts rendered as checklist
  • assertion: tests rendered as given/when/then

review-doc-from-minimal-feature ​

Given:

  • feature_with_only_summary_and_intent: true

Then:

  • assertion: review.md has Intent section
  • assertion: empty sections omitted (no empty Flows heading)

overview-md-unchanged ​

Given:

  • feature_file: true

Then:

  • assertion: overview.md content matches pre-change format
  • assertion: review.md also generated in same directory

Implementation ​

  • Primary: src/generators/markdown.ts
  • Test code status: none

See Also ​

  • usm/gen-markdown
  • usm/mcp-write