issue-planner

# 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 Corpus Generation

Using the research synthesis and SDLC gate requirements, generate the artifact set appropriate for the target phase. Each artifact cross-references the research documents.

**Standard artifact set (Elaboration-level)**:

| Artifact | Path | Template Source |
|----------|------|----------------|
| Use Cases / User Stories | `.aiwg/requirements/UC-<slug>-*.md` | sdlc-complete/templates/requirements/ |
| Architecture Sketch | `.aiwg/architecture/sketch-<slug>.md` | sdlc-complete/templates/analysis-design/ |
| Risk Register | `.aiwg/risks/risks-<slug>.md` | sdlc-complete/templates/risk/ |
| Test Strategy | `.aiwg/testing/test-strategy-<slug>.md` | sdlc-complete/templates/testing/ |
| Security Screening | `.aiwg/security/screening-<slug>.md` | sdlc-complete/templates/security/ |

Generate a lighter set for Inception, heavier for Construction (add ADRs, detailed test plans, CI/CD hooks).

After generation, run the SDLC gate check to confirm completeness:

```
✓ Use cases generated (N stories)
✓ Architecture sketch complete
✓ Risk register populated (N risks)
✓ Test strategy drafted
✓ Security screening done
⏳ Running gate check...
✓ Gate check: corpus complete for <phase> phase
```

If gate check fails, remediate before proceeding to issue generation.

---

### Phase 4: Issue Generation

Translate the artifact corpus and research synthesis into a structured issue backlog.

#### Issue Taxonomy

Every issue gets:

| Field | Options |
|-------|---------|
| **Type label** | `feat`, `docs`, `test`, `infra`, `spike`, `security`, `bug`, `refactor` |
| **Priority** | `P0-critical`, `P1-high`, `P2-medium`, `P3-low` |
| **Phase label** | `phase:inception`, `phase:elaboration`, `phase:construction`, `phase:transition` |
| **Area label** | `area:backend`, `area:frontend`, `area:data`, `area:infra`, `area:docs`, `area:security` |
| **Doc link** | Cross-reference to the artifact that spawned this issue |

#### Priority Assignment Rules

| Condition | Priority |
|-----------|----------|
| Blocks other issues (dependency head) | P0 |
| Security finding or SDLC gate blocker | P0 |
| Core capability required for the objective | P1 |
| Supporting implementation (tests, docs, integration) | P2 |
| Enhancement, optimization, future-proof work | P3 |
| Research spike with uncertain outcome | P2 (timebox) |

#### Dependency Ordering

Analyze issue dependencies and produce a recommended execution sequence:

```
Wave 1 (no dependencies): #N, #N+1
Wave 2 (depends on Wave 1): #N+2, #N+3
Wave 3 (depends on Wave 2): #N+4
```

This is the order to pass to `address-issues`.

#### Issue Body Template

Each filed issue uses this structure:

```markdown
## Summary
<One paragraph describing the work and why it matters for the objective>

## Context
**Objective**: <top-level objective>
**Phase**: <SDLC phase>
**Supporting Docs**:
- @.aiwg/requirements/UC-<slug>.md (use cases)
- @.aiwg/architecture/sketch-<slug>.md (architecture sketch)
- @.aiwg/risks/risks-<slug>.md (risks)

**Research Basis**:
- Best practices: @.aiwg/working/issue-planner/research-best-practices.md
- Vendor docs: @.aiwg/working/issue-planner/research-vendor-docs.md

## Acceptance Criteria
- [ ] <specific, testable criterion>
- [ ] <specific, testable criterion>
- [ ] Tests written and passing
- [ ] Docs updated if applicable

## Dependencies
- Depends on: #<issue numbers>
- Blocks: #<issue numbers>

## Notes
<Key findings from research synthesis relevant to this issue>
```

---

### Phase 5: Plan Preview and Human Approval

**Always** present the complete plan before filing any issues. Even in non-dry-run mode, this gate is mandatory.

Present as a table:

```
## Issue Plan: <objective>

### Research Summary
- N best practices identified
- N current implementations reviewed
- N vendor integrations mapped
- Key finding: <one-liner>

### Supporting Docs Generated
- .aiwg/requirements/UC-<slug>-*.md (N use cases)
- .aiwg/architecture/sketch-<slug>.md
- .aiwg/risks/risks-<slug>.md (N risks)
- .aiwg/testing/test-strategy-<slug>.md

### Issue Backlog (N issues)

| # | Title | Type | Priority | Phase | Depends On | Doc Ref |
|---|-------|------|----------|-------|------------|---------|
| 1 | <title> | feat | P1 | construction | — | UC-001 |
| 2 | <title> | test | P2 | construction | #1 | test-strategy |
| 3 | <title> | docs | P3 | construction | #1 | architecture |
| 4 | <title> | security | P0 | elaboration | — | screening |

### Recommended Execution Order
Wave 1 (parallel): #4, #1
Wave 2 (after Wave 1): #2, #3

### Open Questions
1. <question that needs human decision before work starts>
2. <question>

---
**Proceed to file N issues?** Reply "yes" / "no" / "revise: <guidance>"
```

Wait for explicit human approval before filing.

---

### Phase 6: Issue Filing

On approval, file issues in the order shown (Wave 1 first, then Wave 2, etc.) to ensure issue numbers reflect dependency order.

For each issue:
- File via configured provider (Gitea MCP, GitHub CLI, or local)
- Post a cross-link comment connecting the issue to the research docs
- Record filed issue numbers for the execution-order summary

After all issues filed:

```
## Filed Issues

| Issue | Title | Priority | URL |
|-------|-------|----------|-----|
| #N | <title> | P0 | <url> |
| #N+1 | <title> | P1 | <url> |
...

### Recommended address-issues invocation:
/address-issues <wave-1-numbers> --guidance "<objective summary>"
# Then after wave 1 is resolved:
/address-issues <wave-2-numbers>

Supporting docs: .aiwg/working/issue-planner/ and .aiwg/requirements/
```

---

## Interactive Mode

When `--interactive` is set, ask these questions before Phase 1:

1. **Scope**: Are there technologies, components, or approaches that are explicitly out of scope?
2. **Existing artifacts**: Are there existing requirements, architecture docs, or prior research I should read first?
3. **Phase target**: Which SDLC phase are we in? (inception / elaboration / construction / transition)
4. **Priority bias**: Should I favor security/compliance issues first, or core functionality first?
5. **Timeline**: Is there a sprint or milestone constraint that should influence priority?
6. **Filing approval**: Should I file issues automatically after you see the plan, or always wait for an explicit "yes"?

---

## Priority Order Rationale

The recommended issue order follows these heuristics, applied in sequence:

1. **Gate blockers first** — anything that blocks a phase transition
2. **Security and compliance** — before any feature work begins
3. **Spike/research issues** — resolve unknowns before implementation
4. **Dependency-free implementation** — parallelizable core work
5. **Dependent implementation** — work that needs prior issues resolved
6. **Tests and validation** — after implementation is stable
7. **Documentation** — after implementation and tests
8. **Enhancements and optimizations** — last

This order ensures `address-issues` can make forward progress without hitting dependency blocks.

---

## What Makes This Better Than a Simple Agent or Developer

| Capability | Simple agent | Developer | issue-planner |
|------------|-------------|-----------|---------------|
| Parallel research across 3 dimensions | ✗ | Slow (sequential) | ✓ (one message) |
| SDLC gate check before issue filing | ✗ | Manual | ✓ (automated) |
| Issue-to-artifact traceability | ✗ | Inconsistent | ✓ (every issue) |
| Dependency-aware priority ordering | ✗ | Manual judgment | ✓ (wave analysis) |
| Consistent issue body structure | ✗ | Varies | ✓ (template) |
| Human approval gate before filing | ✗ | Manual | ✓ (mandatory) |
| `address-issues` handoff instructions | ✗ | ✗ | ✓ (generated) |
| Open questions surfaced before work | ✗ | Sometimes | ✓ (systematic) |

---

## Examples

### Example 1: New Integration

**User**: "Plan out Codex plugins support using the research team. File issues, I'll approve before you file anything."

**Extracted**: objective="Codex plugins support", dry-run=false (will ask approval)

**Flow**:
1. Research: Codex plugin API, npm plugin patterns, AIWG deployment architecture
2. Artifacts: use cases (install/package/publish), architecture sketch (.codex-plugin/ format), risks (version drift, marketplace availability)
3. Issues: plugin manifest schema (P1), `package-plugin codex` command (P1), marketplace integration (P2), test coverage (P2), docs (P3)
4. Preview → approval → file

---

### Example 2: Guided Sprint Planning

**User**: "Plan issues for adding HIPAA compliance to the auth module. Use the research team. Focus on security and compliance items first. We're in construction phase already."

**Extracted**: `--guidance "HIPAA compliance, auth module, construction phase, security-first priority"`

**Flow**: Research → security-first issue ordering → HIPAA-specific labels applied → gate-checked against construction criteria

---

### Example 3: Dry Run Review

**User**: "Use the research team and SDLC process to plan out WebSocket support. Show me the issues but don't file them yet."

**Extracted**: `--dry-run`

**Output**: Full plan table with `[DRY RUN — issues not filed]` header. User can revise before committing.

---

### Example 4: Quick Backlog

**User**: "File issues for <my prompt> using the aiwg research team in parallel... SDLC gates... await review."

**This is the canonical trigger pattern.** issue-planner recognizes it and executes the full workflow.

---

### Example 5: Research Induction — Named MCP Service

**User**: "Plan out distributed tracing support. Induct any research you find into our Gitea research repo."

**Extracted**: `--induct-research gitea`

**Flow**:
1. Research pass discovers: OpenTelemetry spec, Jaeger docs, Zipkin paper, "Dapper" Google paper, 3 GitHub repos
2. Phase 2b files 7 induction tasks to the configured Gitea research repo (`mcp__gitea__issue_write`)
3. Each task includes source URL, relevance summary, and induction checklist
4. Continues to Phase 3 (SDLC corpus) → Phase 4 (issues) → Phase 5 (approval)

**Sample induction task filed:**
```
#301 [induct] OpenTelemetry Specification v1.35
Surfaced during: distributed tracing support planning
Stream: vendor-docs
Priority: high — this is the canonical standard we'll implement
```

---

### Example 6: Research Induction — File Path

**User**: "Plan WebAuthn support. Save any references you find to `.aiwg/research/queue/`"

**Extracted**: `--induct-research .aiwg/research/queue/`

**Flow**: Research discovers 9 references. Phase 2b writes `.md` task files to `.aiwg/research/queue/` — one per reference — formatted with the induction body template. These can later be processed with `/induct-research .aiwg/research/queue/`.

---

### Example 7: Research Induction — Environment Variable

**Shell**: `export AIWG_RESEARCH_REPO=https://git.integrolabs.net/roctinam/research`

**User**: "Plan OAuth2 refresh token rotation using the research team."

**Flow**: `AIWG_RESEARCH_REPO` is set; induction is implied. URI is a Gitea instance — issues filed via `mcp__gitea__issue_write` to that repo. No explicit flag needed.

---

## Composition

```
issue-planner <objective>
    │
    ├── Phase 0: Intake + optional interactive discovery
    ├── Phase 1: Parallel research (3 agents simultaneously)
    │   ├── Agent A: Best practices
    │   ├── Agent B: Current research / prior art
    │   └── Agent C: Vendor documentation
    ├── Phase 2: Research synthesis
    ├── Phase 2b: Research induction queue (if --induct-research)
    │   ├── Collect + deduplicate references from all 3 streams
    │   ├── Resolve target (file path | URI | named MCP service)
    │   └── File one induction task per reference → /induct-research
    ├── Phase 3: SDLC doc corpus generation
    │   └── /flow-gate-check <phase> (completeness gate)
    ├── Phase 4: Issue generation (taxonomy + priority + dependency waves)
    ├── Phase 5: Plan preview → HUMAN APPROVAL GATE
    └── Phase 6: Issue filing + address-issues handoff instructions
```

## References

- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/address-issues/SKILL.md — Consume the filed issues
- @$AIWG_ROOT/agentic/code/frameworks/research-complete/skills/induct-research/SKILL.md — Research induction target skill
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/issue-create/SKILL.md — Single issue creation
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/skills/issue-driven-al/SKILL.md — Agent loop per issue
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/flows/flow-gate-check.md — Phase gate criteria
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/templates/ — Artifact templates
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/subagent-scoping.md — Parallel research constraints
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/context-budget.md — Parallel agent limits