Skip to main content

Review and Refine

AI-generated issue files are drafts. Before implementation starts, the team must review the decomposition and decide whether the issue boundaries are correct.

Checklist:

## Issue Review Checklist

- Is each issue small enough for one branch?
- Does each issue contain one main user story?
- Are the functions specific enough to guide implementation?
- Are the required skills correct?
- Are any topic-specific skills missing?
- Is the expected output reviewable?
- Should any issue be split or merged?

The most common failure is an issue that is too large. If one issue contains multiple user goals or multiple unrelated function groups, split it before assigning it to an agent.

Example:

danger

Too large​

ISSUE-2.md  Build product overview page
success

Better​

ISSUE-2.md  Load active products
ISSUE-3.md  Add product search
ISSUE-4.md  Add stock status filter
ISSUE-5.md  Render product overview page

The second common failure is missing skills. If the issue only references SKILLS.md, the agent may miss domain-specific behavior. Add topic skills when the issue needs local knowledge.

Example:

## Required Skills

- `.skills/SKILLS.md`
- `.skills/domains/product-catalog.md`
- `.skills/features/product-overview.md`
- `.skills/engineering-skills/accessibility/forms.md`

The third common failure is asking for code too early. The skill factory should generate stories, issues, functions, and skill references first. Implementation comes after review.

Before Copilot implements an issue, the issue should also define how production readiness will be checked: tests, Storybook states, accessibility expectations, type checks, or CI validation.

Example:​

  • Step 1: Generate issue files
  • Step 2: Review issue files
  • Step 3: Select one issue
  • Step 4: Create one branch
  • Step 5: Ask Copilot to implement that issue
  • Step 6: Validate tests, stories, accessibility, and CI

Mini Exercise​

Take one AI-generated ISSUE-n.md file and review it with the checklist. Rewrite it so it is small enough for one branch and references the right skills.