QA Review

QA Review

Audit a user story implementation against its Example Mapping specification. Reads the EM markdown, finds all implementing code in the codebase, then runs two parallel agents — one for functional coverage, one for code review. Produces a single compact report.

This skill only detects issues — it does not fix them.

Reference

A ready-to-fill EM template is available at em_template.md (in this skill's directory). Share it with the user when they need to write a new spec from scratch.

1. Parse the EM Spec

Read the markdown file at the provided path. Extract a structured summary with these sections:

What to extract

1. User Story title — the first line or heading describing the US
2. Rules — each # Rule N: <title> block. For each rule, extract:
   • Rule number and title
   • Each ## Example N with its setup/action/outcome narrative (preserve the full text)
3. Technical Rules — bullet points under a # Technical rules heading (implementation-focused constraints)
4. User Events — content under # User Events heading: event names, properties, schemas
5. Check Also items — bullet points after "Check also" markers (additional rules/constraints, often separated by dashes)
6. Code References — all backtick-quoted terms across the entire spec (class names, field names, event names like ConflictDetector, space_created, decision)
7. Domain Keywords — key nouns and verbs from rule titles and examples (e.g., "space", "create", "slug", "rename", "conflict")

Handling ambiguity

If a spec item is ambiguous or explicitly deferred (e.g., "TBD", "on verra plus tard", "later"), flag it in the Parsed Spec Summary but exclude it from coverage assessment. Note it in the report as "Deferred — not assessed."

Compile everything into a Parsed Spec Summary formatted as below. The "Full Examples" section preserves the complete raw text of every example — sub-agents need this full context to accurately assess coverage.

## Parsed Spec Summary

### User Story
{title}

### Rules and Examples
Rule 1: {title}
  Example 1: {one-line summary of scenario}
  Example 2: {one-line summary of scenario}
Rule 2: {title}
  Example 1: {one-line summary of scenario}
[...]

### Full Examples (raw text)
{Copy the complete text of every example verbatim from the spec, preserving setup/action/outcome narratives. Do not summarize here — this section is passed to sub-agents so they can assess nuanced behaviors.}

### Technical Rules
- {rule text}
[...]

### Deferred Items
- {item text} — Deferred, not assessed
[...]

### User Events
- {event_name}: {properties}
[...]

### Check Also
- {constraint text}
[...]

### Code References (from backticks)
{list of all backtick-quoted terms}

### Domain Keywords
{list of distinctive nouns/verbs extracted from rules}

2. Select Target Domains

Ask the user which domains this user story touches. Use AskUserQuestion with multiSelect: true:

Packages is always included, even if the user does not select it — it contains domain logic, contracts, events, and infra that all other layers depend on.

Store the user's selection as {target_domains} — a list of domain labels and their directory patterns. All subsequent steps use this to scope their searches.

3. Validate Implementation Exists

Grep 2–3 of the most distinctive backtick-quoted terms from the spec, scoped to the {target_domains} directories only. If fewer than 3 implementing files are found, stop and ask the user to confirm that the US has been fully implemented. Do not proceed with a full review on a partially-implemented or not-yet-started US — the report would be misleading.

4. Build Code Map

Launch a Code Map Agent (subagent_type: general-purpose) using the prompt from agents/code-map-agent.md. Replace:

• {parsed_spec_summary} with the Parsed Spec Summary from step 1
• {target_domains} with the selected domains and their directory patterns from step 2

The agent will search only within the target domain directories, then return a structured Code Map organized by architectural layer. Only layers matching the selected domains will appear in the output.

Wait for the agent to complete before proceeding to step 5.