refine

Issue Refining

Technical breakdown of shaped issues → agent sub-issues.

Linear Config

Setting	Value
Team	Skywalking
Tools	linear_getIssueById, linear_createIssue, linear_updateIssue
Parent State	Shaping → Refining → To Do
Sub-issue State	To Do

Input

• Linear issue ID or URL
• Or: local backlog file reference

Agents

Agent	Focus	Trigger	Sub-agent Type
Aurora	Design, brand, UI/UX	Visual/design work needed	aurora-product-designer
Kokoro	Backend, API, auth, DB	Server-side logic, migrations	kokoro-backend-specialist
Pixel	Frontend, React/Next.js	Components, pages, UI	pixel-frontend-specialist
Flux	Automation, n8n	Workflows, integrations	flux-automation-specialist
Hermes	Deploy, Vercel, monitoring	CI/CD, performance	hermes-deployment-specialist
Centinela	QA, E2E, Playwright	Test coverage	centinela-test-automation-expert
Lumen	SEO, schema	Search optimization	lumen

Flow

1. Load issue → Get from Linear or read local file
2. Resolve open questions → Check for [NEEDS CLARIFICATION] or ## Open Questions in the issue description. If any exist, present them to the user via AskUserQuestion and do not proceed until all are answered. Update the issue description with the resolved answers (remove [NEEDS CLARIFICATION] tags, move answers inline).
3. Analyze scope → Identify which agents needed
4. Ask confirmation → AskUserQuestion to confirm agents
5. Agent reunion → Run /reunion with the confirmed agents to align on technical approach, resolve conflicts, and produce concrete commitments before creating sub-issues. The reunion output (agreements, resolved conflicts, timeline) feeds directly into the sub-issue specs.
6. Create sub-issues → One per agent with technical specs (informed by reunion agreements)
7. Move parent to "To Do" → linear_updateIssue once all sub-issues are created

State transitions: On start → move parent to "Refining". On completion → move parent to "To Do".

Sub-issue Convention

Title format: [{AGENT}] {specific task description}

The agent name in brackets is the delegation signal for Mentat (orchestrator). When Mentat sees [Kokoro] in title, it knows to delegate that sub-issue to the Kokoro sub-agent.

IMPORTANT: Do NOT assign sub-issues to anyone. Leave assigneeId empty. The title prefix is sufficient for orchestration.

Sub-issue Template

linear_createIssue:
  teamId: "Skywalking"
  title: "[{AGENT}] {specific task}"
  parentId: "{parent_id}"
  stateId: "{to_do_state_id}"
  # NO assigneeId - agent name in title is the delegation signal
  description: |
    ## Scope
    {what this agent needs to do}

    ## Technical Specs
    {API endpoints, DB changes, components, etc.}

    ## Files to Touch
    - `path/to/file1.ts`
    - `path/to/file2.tsx`

    ## Acceptance Criteria
    - [ ] {criterion}
    - [ ] {criterion}

    ## Dependencies
    {other sub-issues this depends on}

Technical Specs by Agent

Kokoro (Backend)

• DB migrations (SQL)
• API endpoints (route, method, payload)
• Validation schemas
• Auth requirements

Pixel (Frontend)

• Components to create/modify
• Pages affected
• Props/state requirements
• data-testid for Centinela

Aurora (Design)

• Design tokens needed
• Figma/spec references
• Responsive breakpoints
• Accessibility requirements

Centinela (QA)

• Test scenarios
• data-testid contract from Pixel
• Edge cases to cover
• Performance benchmarks

Hermes (Deploy)

• Env vars needed
• Vercel config changes
• Monitoring setup

Flux (Automation)

• n8n workflow scope
• Triggers and actions
• Error handling

Dependency Detection

Common patterns:

• Kokoro before Pixel (API needed for frontend)
• Aurora before Pixel (design specs needed)
• Pixel before Centinela (test IDs needed)
• All before Hermes (deploy last)

Next Step

After refining:

• /dev {issue-id} → Mentat orchestrates agent work
  • Delegates sub-issues based on [Agent] prefix
  • Monitors progress, resolves doubts
  • Validates acceptance criteria
  • Comments on completion in Linear

Example Output

For SKY-45 (WhatsApp button):

Parent: [Feature] WhatsApp button configurable
├── [Kokoro] Migration + API validation
│   - ALTER TABLE tenants ADD whatsapp_number
│   - Validation endpoint
├── [Pixel] WhatsAppButton component + dashboard UI
│   - components/storefront/WhatsAppButton.tsx
│   - Integration in 4 templates
│   - Dashboard settings UI
└── [Centinela] E2E tests
    - Button visibility
    - Click behavior
    - Dashboard config flow

Next: /dev SKY-45