# Issue Plan

> Break a design goal into detailed, dependency-ordered GitHub issues. Use when the user has a feature idea, architectural change, or refactor and wants a structured plan with issues ready for sprint execution. Triggers include "plan this", "break this down", "create issues for this", or presenting a design/architecture to implement.

- Skill: `michaelliv/issue-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add michaelliv/issue-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/michaelliv/issue-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: michaelliv (https://skillmd.com/u/michaelliv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/michaelliv/issue-plan

---


# Issue Plan

You turn a design goal into a set of detailed, dependency-ordered GitHub issues ready for execution.

## Prerequisites

```bash
which gh || echo "Install GitHub CLI: https://cli.github.com/"
git --version
```

The project must have a GitHub remote.

## Workflow

### 1. Understand the Goal

Before planning, understand:
- **What** is being built or changed
- **Why** — what problem it solves
- **Constraints** — what's off the table, what's non-negotiable
- **Existing code** — read the codebase to understand current architecture

Ask clarifying questions. Challenge assumptions. Surface contradictions early ("you said X stays in core but also listed it as an extension — which is it?").

**Read before planning.** Use `gh`, `find`, `grep`, and `read` to understand:
- Project structure and conventions (AGENTS.md, README.md)
- Existing code that will be modified or extended
- Test patterns and CI setup
- Related docs or prior art

### 2. Design Discussion

Work through the design interactively:
- Propose options with tradeoffs, let the user decide
- Identify what's core vs what's pluggable
- Surface dependency relationships ("X needs Y to exist first")
- Flag scope creep ("that's a separate concern — park it for later")
- Converge on key decisions before writing issues

Track decisions as they're made. These become context in the issues.

### 3. Topological Breakdown

Break the work into phases ordered by dependencies:

```
Phase 1: Foundation (no dependencies)
  - 1.1 Types and interfaces
  - 1.2 Database schema changes
  - 1.3 Core system changes

Phase 2: Core Implementation (depends on Phase 1)
  - 2.1 Loader/registry
  - 2.2 API implementation
  - 2.3 Hook system

Phase 3: Integration (depends on Phase 2)
  - 3.1 Wire into existing systems
  - 3.2 Update CLI
```

**Rules:**
- Items within a phase can be done in parallel
- Each phase depends only on prior phases
- Show the dependency graph explicitly:
  ```
  Phase 1 ──► Phase 2 ──► Phase 3 ──► Phase 5
                      ├──► Phase 4 ──┘
                      └──► Phase 6
  ```

Present to the user for confirmation before creating issues.

### 4. Create GitHub Labels

Create phase labels for tracking:

```bash
gh label create "phase-1" --description "Foundation" --color "0e8a16"
gh label create "phase-2" --description "Core Implementation" --color "1d76db"
# ... etc
```

Plus a feature label for filtering:

```bash
gh label create "<feature-name>" --description "<description>" --color "6f42c1"
```

### 5. Create Issues

For each task, create a detailed GitHub issue. Every issue must have:

#### Summary
One paragraph: what this does and why it matters.

#### Implementation
Concrete code — not pseudocode, not vague descriptions:
- TypeScript interfaces and type definitions
- SQL schemas with exact CREATE TABLE statements
- Function signatures with parameter types
- Example usage showing the API in action

```typescript
// Good: actual interface the implementer will use
export function registerPermission(
  name: string,
  opts: { defaultRoles: string[] }
): void {
  if (BUILT_IN_PERMISSIONS.has(name)) {
    throw new Error(`Permission "${name}" is built-in`);
  }
  registeredPermissions.set(name, opts);
}

// Bad: vague hand-waving
// Add a function to register permissions
```

#### File Locations
Exact paths for new and modified files:
```
New: src/extensions/types.ts
Modified: src/core/permissions.ts
Modified: src/storage/db.ts
```

#### Dependencies
Explicit issue references:
```
## Dependencies
- #77 (Extension types)
- #78 (extension_state DB table)
```

#### Error Handling
What can go wrong and what to do:
- Invalid input → clear error message
- Collision → throw or skip with warning
- External failure → fallback behavior

#### Integration Points
Where this connects to existing code. Reference specific functions, methods, or patterns:
```
### Integration with runtime
In `MercuryCoreRuntime.executePrompt()` — before spawning the container,
emit the hook. Apply returned mutations. If blocked, return early.
```

#### Acceptance Criteria
Specific, testable checkboxes:
```
## Acceptance criteria
- [ ] Extensions can register permissions at runtime
- [ ] Built-in permission names are protected from override
- [ ] Admin role automatically gets new extension permissions
- [ ] Existing permission tests still pass
- [ ] New tests for dynamic registration
```

### Issue Creation Command

```bash
gh issue create \
  --title "<phase>.<number> <Title>" \
  --label "<feature>,<phase>,enhancement" \
  --body '<body>'
```

**Title format:** `<phase>.<number> <Title>` (e.g., "1.1 Extension types and interfaces")

### 6. Verify

After creating all issues, verify:

```bash
gh issue list --label <feature> --state open
```

Present a summary table:

```
Phase 1: Foundation
  #77  1.1 Extension types and interfaces
  #78  1.2 Extension state DB table
  #79  1.3 Dynamic permissions

Phase 2: Core Implementation
  #80  2.1 Extension loader
  #81  2.2 API implementation
  ...
```

## Issue Quality Checklist

Before creating each issue, verify:

- [ ] **Self-contained**: A developer can pick this up without reading other issues
- [ ] **Concrete code**: Interfaces, schemas, signatures — not descriptions of code
- [ ] **File paths**: Exact new/modified file locations
- [ ] **Dependencies explicit**: Issue numbers, not vague "after the loader is done"
- [ ] **Error cases covered**: What happens when things go wrong
- [ ] **Acceptance criteria testable**: Each checkbox can be verified by running code
- [ ] **Scope appropriate**: Not too big (>1 day), not too small (trivial)
- [ ] **Context included**: Key decisions and constraints that inform implementation

## Anti-patterns

- **Vague issues**: "Implement the extension system" — too broad, no code
- **Missing dependencies**: Issues that can't be started because prerequisites aren't identified
- **Implementation-free**: "Add a new table" without the schema
- **Untestable criteria**: "Works correctly" — what does that mean?
- **Kitchen sink**: One issue that does 5 things — split it
- **Orphan issues**: Issues with no dependency chain — where do they fit?

## Tips

- **Read the codebase first** — issues that reference real code are 10x more useful
- **Code snippets > descriptions** — show the interface, not a paragraph about it
- **Name the files** — "add to db.ts" not "add to the database layer"
- **Surface decisions** — document why, not just what
- **Keep phases small** — 3-5 issues per phase, 5-7 phases max
- **Parallel where possible** — don't serialize unnecessarily
- **Tests are acceptance criteria** — if you can't test it, you can't ship it