Issue-Driven Development

Overview

The master coding process. Every step references specific skills. Follow in order.

Core principle: No work without an issue. No shortcuts. No exceptions.

Announce at start: "I'm using issue-driven-development to implement this work."

Before Starting

Create TodoWrite items for each step you'll execute. This is not optional.

The 13-Step Process

Step 1: Issue Check

Question: Am I working on a clearly defined GitHub issue that is tracked in the project board?

Actions:

• If no issue exists → Create one using issue-prerequisite skill
• If issue is vague → Ask questions, UPDATE the issue, then proceed
• VERIFY issue is in GitHub Project with correct fields (not assumed - verified)

Verification (MANDATORY) - uses cached data:

# Verify issue is in project board (0 API calls - uses cache)
ITEM_ID=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.content.number == [ISSUE_NUMBER]) | .id")

if [ -z "$ITEM_ID" ] || [ "$ITEM_ID" = "null" ]; then
  echo "BLOCKED: Issue not in project board. Add it before proceeding."
  # Add to project (1 API call) and refresh cache (1 API call)
  gh project item-add "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
    --url "$(gh issue view [ISSUE_NUMBER] --json url -q .url)"
  export GH_CACHE_ITEMS=$(gh project item-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json)
  ITEM_ID=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.content.number == [ISSUE_NUMBER]) | .id")
fi

# Verify Status field is set (0 API calls - uses cache)
STATUS=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.id == \"$ITEM_ID\") | .status.name")

if [ -z "$STATUS" ] || [ "$STATUS" = "null" ]; then
  echo "BLOCKED: Issue has no Status in project. Set Status before proceeding."
fi

Skill: issue-prerequisite, project-board-enforcement

Gate: Do not proceed unless:

1. GitHub issue URL exists
2. Issue is verified in GitHub Project (ITEM_ID obtained)
3. Status field is set (Ready, Backlog, or In Progress)

---

Step 2: Read Comments

Question: Are there comments on the issue I need to read?

Actions:

• Read all comments on the issue
• Note any decisions, clarifications, or context
• Check for linked issues or PRs

Skill: issue-lifecycle

---

Step 3: Size Check

Question: Is this issue too large for a single task?

Indicators of too-large:

• More than 5 acceptance criteria
• Touches more than 3 unrelated areas
• Estimated > 1 context window of work
• Multiple independent deliverables

If too large:

1. Break into sub-issues using issue-decomposition
2. Link sub-issues to parent
3. Update parent issue as parent label
4. Loop back to Step 1 with first sub-issue

Skill: issue-decomposition

---

Step 4: Memory Search

Question: Is there previous work on this issue or related issues?

Actions:

• Search episodic-memory for issue number, feature name, related terms
• Search mcp__memory knowledge graph for related entities
• Note any relevant context, decisions, or gotchas

Skill: memory-integration

---

Step 5: Research

Question: Do I need to perform research to complete this task?

Research types:

1. Repository documentation - README, CONTRIBUTING, docs/
2. Existing codebase - Similar patterns, related code
3. Online resources - API docs, library references, Stack Overflow

Actions:

• Conduct necessary research
• Document findings in issue comment if significant
• Note any blockers or concerns

Skill: pre-work-research

---

Step 6: Branch Check & Status Update

Question: Am I on the correct branch AND has the project status been updated?

Rules:

• NEVER work on main
• Create feature branch if needed
• Branch from correct base (usually main, sometimes existing feature branch)

Naming: feature/issue-123-short-description or fix/issue-456-bug-name

Project Status Update (MANDATORY) - uses cached IDs:

When starting work, update project board Status to "In Progress":

# Use cached IDs (0 API calls for lookups)
# GH_PROJECT_ID, GH_STATUS_FIELD_ID, GH_STATUS_IN_PROGRESS_ID set by session-start

# Update status to In Progress (1 API call)
gh project item-edit --project-id "$GH_PROJECT_ID" --id "$ITEM_ID" \
  --field-id "$GH_STATUS_FIELD_ID" --single-select-option-id "$GH_STATUS_IN_PROGRESS_ID"

# Refresh cache and verify (1 API call)
export GH_CACHE_ITEMS=$(gh project item-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json)
NEW_STATUS=$(echo "$GH_CACHE_ITEMS" | jq -r ".items[] | select(.id == \"$ITEM_ID\") | .status.name")

if [ "$NEW_STATUS" != "In Progress" ]; then
  echo "ERROR: Failed to update project status. Cannot proceed."
  exit 1
fi

Skill: branch-discipline, project-board-enforcement

Gate: Do not proceed if:

1. On main branch
2. Project Status not updated to "In Progress"

---

Step 7: TDD Development

**Pro

...