issue-planner

What this skill does

# Issue Planner

Transform a high-level objective into a fully researched, SDLC-gated issue backlog — ready for `address-issues` — without a human having to manually research, write docs, or decide priority order.

## Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

- "plan out <feature>" → full research + issue filing workflow
- "file issues for <objective>" → issue-planner with dry-run preview first
- "create a backlog for <objective>" → issue-planner with priority ordering
- "research and plan <topic>" → parallel research pass then issue filing
- "use the research team to plan <X>" → explicit parallel research dispatch
- "plan issues for <X> using SDLC gates" → gate-checked issue generation
- "I need issues for <X>" → issue-planner in interactive mode to confirm scope

## Parameters

### `<objective>` (required)
The feature, capability, integration, or initiative to plan. Can be a one-liner or a multi-paragraph brief.

### `--interactive` (optional)
Ask discovery questions before researching. Surfaces: scope constraints, excluded technologies, existing artifacts, target phase, priority bias (bugs-first vs value-first).

### `--dry-run` (optional)
Generate the full plan and issue list but do not file any issues. Outputs a preview table for human review.

### `--guidance "text"` (optional)
Upfront direction that shapes research focus, prioritization, and scope without interactive prompts.

Examples:
- `--guidance "We're in Construction phase, skip Inception artifacts"`
- `--guidance "Security is top priority, HIPAA compliance required"`
- `--guidance "Quick wins only — scope to 2-week sprint"`

### `--provider` (optional)
Override the default issue tracker (`gitea` | `github` | `local`). Defaults to project config in `.aiwg/config.yaml` or `CLAUDE.md`.

### `--skip-research` (optional)
Skip the parallel research pass and go straight to SDLC doc generation. Use when research was already done externally.

### `--phase` (optional)
Target SDLC phase for artifact generation (`inception` | `elaboration` | `construction` | `transition`). Determines which templates are used and which gate criteria are checked.

### `--induct-research <target>` (optional)
After research synthesis, extract all discovered references and file tracking tasks to induct them into a research repository. Can also be set via `AIWG_RESEARCH_REPO` environment variable.

**Target formats:**

| Format | Example | Behavior |
|--------|---------|----------|
| File path | `--induct-research .aiwg/research/queue/` | Creates one Markdown task file per reference in the specified directory |
| URI | `--induct-research https://git.integrolabs.net/roctinam/research` | Infers the system from the URL (Gitea, GitHub, Jira, etc.) and files issues via the appropriate API or MCP tool |
| Named MCP service | `--induct-research gitea` | Uses the named MCP service directly (e.g. `mcp__gitea__issue_write`) |
| Named MCP service | `--induct-research codehound` | Uses Hound MCP to register references in the Hound search index |

**Env var fallback:** If `AIWG_RESEARCH_REPO` is set, `--induct-research` is implied with the env var value as the target. Explicit flag overrides the env var.

**What gets inducted:** Every external URL, paper, RFC, repo, or specification surfaced during Phase 1 research — one tracking task per reference.

**Induction task body template:**

```markdown
## Reference Induction

**Source**: <URL or file path>
**Surfaced by**: issue-planner research phase for "<objective>"
**Research stream**: <best-practices | current-state | vendor-docs>

## Relevance Summary
<One paragraph from the research agent explaining why this reference matters>

## Suggested Priority
<high | medium | low> — <rationale>

## Induction Checklist
- [ ] Read and annotate full source
- [ ] Extract key insights as Zettelkasten notes
- [ ] Cross-reference with existing corpus
- [ ] Tag with topic taxonomy
- [ ] Mark inducted in research queue

## Links
- Objective: <top-level planning objective this was surfaced for>
- Research file: @.aiwg/working/issue-planner/research-<stream>.md
```

---

## Execution Flow

### Phase 0: Intake

1. Parse `<objective>` from the user's message.
2. If `--interactive`: ask discovery questions (see Interactive Mode below).
3. If `--guidance`: incorporate upfront direction throughout all phases.
4. Confirm understanding before launching:

```
Understood. Planning: <paraphrased objective>

Research pass: 3 parallel agents (best practices, current research, vendor docs)
Artifacts: requirements, architecture sketch, risk register, test strategy
Provider: gitea (roctinam/aiwg)
Mode: [dry-run | live filing]

Starting research...
```

---

### Phase 1: Parallel Research (3 agents, single message)

Dispatch three focused research agents simultaneously. Each writes its output to `.aiwg/working/issue-planner/`:

**Agent A — Best Practices**
```
Objective: <objective>
Task: Research industry best practices, design patterns, and architectural guidance relevant to this objective.
Output: .aiwg/working/issue-planner/research-best-practices.md
Include: patterns, anti-patterns, recommended approaches, key trade-offs
```

**Agent B — Current Research & Prior Art**
```
Objective: <objective>
Task: Survey recent research, conference talks, open-source implementations, and community knowledge relevant to this objective.
Output: .aiwg/working/issue-planner/research-current-state.md
Include: recent developments (≤2 years), noteworthy implementations, emerging standards
```

**Agent C — Vendor Documentation**
```
Objective: <objective>
Task: Review official vendor documentation, API references, and integration guides for all relevant tools and platforms.
Output: .aiwg/working/issue-planner/research-vendor-docs.md
Include: official capabilities, known limitations, version requirements, migration notes
```

Progress indicator during research:
```
⏳ Research pass (3 parallel agents)...
  ⏳ A: Best practices...
  ⏳ B: Current research...
  ⏳ C: Vendor docs...
```

---

### Phase 2: Research Synthesis

Read all three research outputs and synthesize a consolidated brief:

```
✓ A: Best practices complete
✓ B: Current research complete
✓ C: Vendor docs complete
⏳ Synthesizing research...
```

Synthesis output (`.aiwg/working/issue-planner/research-synthesis.md`):
- Key findings per research stream
- Consensus recommendations
- Identified risks and unknowns
- Technology/approach decisions surfaced by research
- Open questions requiring human input

---

### Phase 2b: Research Induction Queue (if `--induct-research` or `AIWG_RESEARCH_REPO` set)

Extract all external references discovered across the three research streams and queue them for induction.

**Steps:**

1. **Collect references** — scan all three research output files for external URLs, paper titles, RFC numbers, repo links, and named specifications
2. **Deduplicate** — remove references already present in the target repository (if queryable)
3. **Resolve target** — determine filing method from the provided target:
   - **File path**: write `.md` task files to the directory (create if needed)
   - **URI**: detect host (Gitea domain → `mcp__gitea__issue_write`, GitHub → `gh issue create`, Jira → REST API)
   - **Named MCP service**: call the service's write tool directly
4. **File one induction task per reference** using the standard induction body template
5. **Report** induction summary before proceeding to Phase 3

```
⏳ Research induction queue...
  Found 12 references across 3 research streams
  Target: gitea (roctinam/research)
  Filing induction tasks...
  ✓ Filed #301: RFC 9110 HTTP Semantics
  ✓ Filed #302: "Designing Data-Intensive Applications" (Kleppmann)
  ✓ Filed #303: github.com/expressjs/express
  ... (9 more)
✓ Induction queue: 12 tasks filed
```

If `--dry-run` is set, list the references that would be inducted without filing.

---

### Phase 3: SDLC Doc Co