issue-workflow

name	issue-workflow
description	Issue-driven development workflow using GitHub issues as the source of truth. Use when asking "what's next?", checking project status, updating progress, or managing work priorities.

Issue-Driven Workflow Skill

Use GitHub issues as the north star for all project work. This skill defines how to check status, pick work, track progress, and maintain issue hygiene.

When to Use

Use this skill when:

• User asks "what's next?" or "what should I work on?"
• Starting a new work session
• Completing a task and need to update progress
• Planning what to build
• Reviewing project status

Core Principles

1. Issues are the source of truth - All planned work lives in GitHub issues
2. Epics track large initiatives - Use epic issues with checklists for multi-part work
3. Keep issues updated - Mark items complete as work finishes
4. Prioritized build order - Follow the documented sequence in epics
5. Create issues for new work - Don't start significant work without an issue

Workflow: Starting a New Conversation

At the start of each new conversation, pull issue context to understand current state:

Step 1: Pull Recent Issue Context

# View the active epic with all comments
gh issue view 70 --repo owner/repo --comments

# View recently completed issues with learnings
gh issue view 78 --repo owner/repo --comments

This gives you:

• Current epic status and progress
• Recent decisions and learnings
• Architecture choices made
• What's been completed
• What's next in the build order

Why this matters:

• Each conversation starts fresh with no memory
• Comments capture context across sessions
• Decisions and patterns are preserved
• You avoid re-asking questions or repeating work

Step 2: Understand Current State

From the issue comments, identify:

• What phase/sprint we're in
• What was just completed
• Key architectural decisions
• Patterns being followed
• Blockers or discoveries

Now you have full context to continue work seamlessly.

---

Workflow: "What's Next?"

When user asks what to work on:

Step 1: Find Active Epic

# Check for active epics (label:epic, state:open)
gh issue list --label epic --state open

Or use MCP tool:

mcp__github__search_issues with q: "repo:owner/repo is:issue is:open label:epic"

Step 2: Read Epic Status

Fetch the epic issue and look for:

• Current Status section - What phase are we in?
• Build Order section - What's marked as "Next"?
• Checkboxes - What's done vs pending?

Step 3: Identify Next Task

From the epic's build order, find the first unchecked item. Consider:

• Blockers - Is this blocked by another task?
• Dependencies - Does this need something built first?
• Complexity - Is this a quick win or major effort?

Step 4: Present Options with Complexity Score

Score each option using complexity-scoring skill (1-5 scale):

## Next Steps from Epic #XX

Based on the build order, here are your options:

1. **[Task Name]** - [Brief description]
   - Complexity: [1-5]/5 → [No plan / Plan recommended]
   - Blocked by: None / [Blocker]

2. **[Alternative Task]** - [Brief description]
   - Complexity: [1-5]/5 → [No plan / Plan recommended]

What would you like to work on?

→ See complexity-scoring skill for how to score tasks.

Step 5: Score and Route (when user picks a task)

When user selects a task, route based on complexity score:

Score	Action
1-2	Proceed directly with implementation
3	Use judgment - proceed or enter plan mode
4-5	Enter plan mode before writing code

Example routing:

User: "let's do FilterPanel"

Claude: "FilterPanel scores **4/5** on complexity:
- Multiple design decisions (price range, checkboxes, layout)
- Integrates with search state
- Needs responsive behavior

Entering plan mode to design the approach first."
[Uses EnterPlanMode tool]

For tasks scoring ≤2:

User: "fix the typo in Button"

Claude: "Simple fix (1/5). Handling directly."
[Proceeds without plan mode]

Workflow: Updating Progress

After completing work:

Step 1: Identify What Changed

• Which checklist items are now complete?
• Did we discover new work needed?
• Are there new blockers?

Step 2: Close Completed Sub-Issues (CRITICAL)

Always close issues immediately when their work is complete. Don't leave completed work with open issues.

mcp__github__update_issue({
  owner: "sernstberger",
  repo: "base-joy",
  issue_number: XX,
  state: "closed"
})

Step 3: Verify Quality Before Commit

Always run checks before committing. This catches issues early and keeps the codebase clean.

# TypeScript check (zero errors required)
npx tsc --noEmit -p libs/ui/styled/tsconfig.json

# Run tests (all must pass)
yarn test

# Optional: lint check
yarn lint

If errors exist:

• TypeScript errors: Fix before committing
• Test failures: Fix before committing
• Pre-existing errors: Fix in a separate commit (see "Pre-existing Error Cleanup" section)

Step 4: Commit Changes

Always commit completed work before updating issues. This keeps code and issue state in sync.

git add <changed-files>
git commit -m "feat(scope): description

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>"

Commit message prefixes:

• feat - New features/components
• fix - Bug fixes
• refactor - Code restructuring
• docs - Documentation
• test - Tests

Step 5: Update Epic Issue (CRITICAL)

Always update the epic checklist immediately after completing work. This is essential for cross-conversation continuity.

Use mcp__github__update_issue to:

• Check off completed items: - [x] Item ✅
• Update "Current Status" section
• Move "Next" marker to next item
• Add any new discovered tasks

Example:

gh issue edit 70 --body "$(cat <<'EOF'
[Full updated epic body with checked boxes]
EOF
)"

Step 6: Add Learnings Comment (CRITICAL)

Document key decisions and learnings on closed issues. This creates context for future conversations.

When closing a sub-issue, add a comment capturing:

• Pattern Followed - What existing code/patterns were used as reference
• Key Decisions - Important choices made during implementation
• Files Created/Modified - Summary of changes
• Next Steps - What comes after this work
• Gotchas/Learnings - Things that weren't obvious or could help later

Example:

gh issue comment 78 --repo owner/repo --body "## Learnings from Scaffolding

**Pattern Followed:**
- Used vacation-rental demo as reference
- Port 5175 (next sequential port)

**Key Decisions:**
1. Created RESEARCH.md upfront to capture specs
2. Added Settings page early (not in original spec)
3. Decided on org simulation approach

**Files Created:**
- 22 files, 681 lines
- Complete app structure ready

**Next Steps:**
- Sprint 0, task 5: Mock data (#80)
- Sprint 1: Enhanced components"

Step 7: Add Progress Comment to Epic

Update the epic with progress commentary. This helps understand the journey when reviewing later.

Add a comment to the epic summarizing:

• What was completed
• Status update (X% complete, Y/Z tasks done)
• Key discoveries or scope changes
• Architecture decisions made
• What's next

Example:

gh issue comment 70 --repo owner/repo --body "## Sprint 0 Progress Update

✅ **Completed:**
- #78 - Scaffold calendar demo app
- RESEARCH.md created

**Status:** Phase 0: Infrastructure - 80% complete (4/5 tasks)

**Key Discoveries:**
1. Settings needs 8 major sections (created #79)
2. Mock org data needed (created #80)

**Next Task:** Sprint 0, #5 - Mock data"

Step 8: Verify Issue Hygiene

Before ending a session, check:

• All completed work has closed issues
• Epic checklists reflect actual progress
• No "orphan" open issues for done work
• Learnings documented on closed issues
• Progress comments added to epic

Epic Issue Template

When creating new epics, use this structure:

## Overview

[Brief description of the initiative]

## Current Status

**Phase X: [Phase Name]** [✅ Complete / 🔄 In Progress]
- Bullet points of what's done
- What's currently being worked on

**Next Up:** [Specific next task]

---

## [Section 1 - e.g., Pages]

- [ ] **Item 1** - Description
- [ ] **Item 2** - Description
- [x] **Item 3** - Description ✅

## [Section 2 - e.g., Components]

### Priority Level
- [ ] #XX Item (links to sub-issue if exists)
- [x] #YY Item ✅

## Build Order

1. ~~Completed item~~ ✅
2. ~~Another completed~~ ✅
3. **Current item** ← Next
4. Future item
5. Future item (blocked by #3)

## Related

- Parent: #XX (if this is part of larger initiative)
- Sub-issues: #YY, #ZZ

Creating Sub-Issues

For significant tasks, create dedicated issues:

## Summary

[What needs to be built]

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Technical Notes

[Implementation hints, patterns to follow]

## Related

- Epic: #XX

Labels to Use

Label	Purpose
epic	Large multi-part initiatives
component	Library component work
demo-app	Demo application work
docs	Documentation
bug	Bug fixes
P0, P1, P2	Priority levels
blocked	Waiting on something

Commands Reference

List open epics

gh issue list --label epic --state open

View specific issue

gh issue view 43

Update issue body

mcp__github__update_issue with owner, repo, issue_number, body

Create new issue

mcp__github__create_issue with owner, repo, title, body, labels

Search issues

mcp__github__search_issues with q: "repo:owner/repo [search terms]"

Context Management

Between tasks in the same session, use /compact to:

• Preserve epic status and recent decisions
• Trim verbose implementation history
• Maintain rhythm without context bloat

Use /clear when:

• Starting a new session
• Switching to a different epic
• Context feels stale or confused

Tips

1. Daily check-in - Start sessions by checking epic status
2. Small updates - Update issues after each meaningful chunk of work
3. Link everything - Reference issue numbers in commits and other issues
4. Celebrate wins - Marking items complete feels good, do it promptly
5. Keep build order realistic - Adjust if priorities change
6. Don't over-issue - Small tasks don't need their own issue
7. Compact between tasks - Keep context fresh within a session

Example Session Flow

Starting Fresh

User: "what's next?"

Claude: [Pulls epic #70 with --comments]
        [Reads learnings from #78]
        [Understands: Sprint 0 is 80% done, mock data is next]
        [Presents: "Based on epic #70, next is task #5: Mock data (#80)"]

User: "let's do it"

Claude: [Creates TodoWrite for tracking]
        [Implements mock data]
        [Runs type check]
        [Commits the changes]

        [Updates epic #70: checks box for task #5]
        [Adds learnings comment to #80]
        [Adds progress comment to #70]

User: "what's next?"

Claude: [Fetches updated epic #70]
        [Shows: "Sprint 0 complete! Sprint 1 starts with CalendarHeader"]

Full Update Workflow

User: "commit the scaffolding changes"

Claude: [Runs git status, git diff]
        [Creates commit with proper message]

        ⚠️ **CRITICAL STEP - Update Issues** ⚠️

        [gh issue edit 70 - checks box for #78]
        [gh issue comment 78 - adds learnings]
        [gh issue comment 70 - adds progress update]

        "✅ Committed and updated epic #70!"

Stub-First Development

When building pages or complex features, prefer a stub-first approach:

1. Create the page structure with placeholder stubs for components not yet built
2. Wire up routing and navigation so the page is accessible
3. Implement working sections with existing components
4. Leave clear stubs for future work with descriptive names

Stub Pattern

function Stub({ name, className = '' }: { name: string; className?: string }) {
  return (
    <div className={`bg-neutral-100 border-2 border-dashed border-neutral-300
                     rounded-lg flex items-center justify-center
                     text-neutral-500 font-mono text-sm ${className}`}>
      {name}
    </div>
  );
}

// Usage
<Stub name="ImageGallery" className="h-[400px]" />
<Stub name="ReviewsSection (RatingBreakdown + ReviewCards)" className="h-[300px]" />

Benefits

• See context early - View components in their actual page context
• Identify gaps - Stubs clearly show what's missing
• Parallel work - Multiple stubs can be filled independently
• Incremental progress - Page is functional even with placeholders

Pre-existing Error Cleanup

When running type checks or linting, you may encounter pre-existing errors unrelated to your current work. Don't ignore these - clean them up in a separate commit.

Workflow

1. After completing a feature, run type check: yarn workspace @base-joy/[app] tsc --noEmit
2. Identify pre-existing errors (errors not in files you just modified)
3. Launch a background agent to fix them:

Task tool with subagent_type: "general-purpose"
Prompt: "Fix the following pre-existing TypeScript/ESLint errors.
         Keep fixes minimal and focused. Do NOT modify [list of files
         from current feature]. Commit fixes separately."

4. Commit separately with message: fix: clean up pre-existing lint/type errors

Why This Matters

• Avoid technical debt accumulation - Errors compound over time
• Keep CI green - Pre-existing errors can break builds
• Separate concerns - Feature commits stay focused, cleanup is isolated
• Maintain quality - Don't normalize broken builds

What to Fix

• Unused imports/variables (@typescript-eslint/no-unused-vars)
• Type errors in existing code
• ESLint warnings that are straightforward to fix

What to Skip (for now)

• Complex type issues requiring architectural changes
• Warnings that require discussion (mark as TODO)
• Third-party library issues

Related Skills

• complexity-scoring - 1-5 scale for task complexity (used in Step 4-5)
• task-orchestration - Model selection, parallelization based on complexity
• demo-app-researcher - Research apps before creating epics
• component-generator - Build new library components
• playwright-dev-workflow - Show user progress in real-time during UI development