Brain Dump Workflow Skill

This skill guides you through the Brain Dump quality workflow, ensuring consistent code quality and proper tracking across all AI-assisted development.

Overview

Brain Dump implements a structured quality workflow inspired by Dillon Mulroy's "tracer review" pattern:

ready → in_progress → ai_review → human_review → done

Each phase has specific requirements and MCP tools to use.

Starting Work

When you begin working on a ticket:

// 1. Start the ticket work (creates git branch, updates status)
mcp__brain-dump__workflow "start-work"({ ticketId: "<ticket-id>" })

// 2. Create a session for state tracking
mcp__brain-dump__session "create"({ ticketId: "<ticket-id>" })
// Returns: { sessionId: "..." }

// 3. Update state as you progress
mcp__brain-dump__session "update-state"({
  sessionId: "<session-id>",
  state: "analyzing",
  metadata: { message: "Reading ticket requirements" }
})

State Transitions

Update your state as you work through phases:

State	When to use
analyzing	Reading and understanding requirements
implementing	Writing or modifying source code
testing	Running tests to verify behavior
committing	Creating git commits
reviewing	Final self-review before completing

Example:

mcp__brain-dump__session "update-state"({
  sessionId: "<session-id>",
  state: "implementing",
  metadata: { message: "Adding new API endpoint" }
})

Completing Work

When implementation is done:

// 1. Run validation discovered from this project's docs/config.
// Do not assume pnpm/npm; use the project-standard commands.

// 2. Complete the ticket work
mcp__brain-dump__workflow "complete-work"({
  ticketId: "<ticket-id>",
  summary: "Added new API endpoint with validation and tests"
})
// Status becomes: ai_review

AI Review Phase

During AI review, run code review agents:

// Submit findings from review
mcp__brain-dump__review "submit-finding"({
  ticketId: "<ticket-id>",
  agent: "code-reviewer",
  severity: "major",
  category: "error-handling",
  description: "Missing error handling for null input"
})

// After fixing, mark as fixed
mcp__brain-dump__review "mark-fixed"({
  findingId: "<finding-id>",
  fixStatus: "fixed",
  fixDescription: "Added null check at line 45"
})

// Check if all critical/major issues are resolved
mcp__brain-dump__review "check-complete"({ ticketId: "<ticket-id>" })
// Returns: { canProceedToHumanReview: true/false }

Demo Generation

When AI review passes (all critical/major findings fixed):

mcp__brain-dump__review "generate-demo"({
  ticketId: "<ticket-id>",
  steps: [
    { order: 1, description: "Navigate to /settings", expectedOutcome: "Settings page loads", type: "manual" },
    { order: 2, description: "Click 'Add User' button", expectedOutcome: "Modal appears", type: "visual" },
    { order: 3, description: "Submit form with valid data", expectedOutcome: "Success message shown", type: "manual" }
  ]
})
// Status becomes: human_review

Important: Stop at Human Review

After generating the demo script, STOP. Do not attempt to auto-approve the ticket.

The human reviewer will:

1. Follow the demo steps
2. Call mcp__brain-dump__review "submit-feedback"() with their verdict
3. The ticket moves to done only after human approval

Telemetry

All your tool usage is automatically captured by the telemetry hooks:

• Tool start/end times
• Correlation IDs for pairing events
• Session context

This provides full audit trails for enterprise compliance.

Quick Reference

Action	MCP Tool
Start ticket	workflow "start-work"({ ticketId })
Create session	session "create"({ ticketId })
Update state	session "update-state"({ sessionId, state })
Complete work	workflow "complete-work"({ ticketId, summary })
Submit finding	review "submit-finding"({ ticketId, agent, severity, category, description })
Fix finding	review "mark-fixed"({ findingId, fixStatus })
Check review	review "check-complete"({ ticketId })
Generate demo	review "generate-demo"({ ticketId, steps })