initiative-architecture

What this skill does

# Initiative Architecture

## Overview

When work is too large for a single epic, it becomes an **initiative**. This skill methodically investigates, documents, and structures massive requests into a resumable, tractable plan.

**Core principle:** Document everything. Every unknown answered, every decision made, every assumption validated. The architecture must be resumable by a fresh context.

**Announce at start:** "I'm using initiative-architecture to plan this massive request. This will involve investigation, documentation, and structured decomposition."

## What is an Initiative?

An initiative is work that:
- Spans multiple epics (feature areas)
- Requires significant research before planning
- May need new infrastructure or capabilities
- Will take weeks to months to complete
- Has many unknowns that need investigation

## The Architecture Process

```
┌─────────────────────────────────────────────────────────────────────┐
│                    INITIATIVE RECEIVED                               │
│              (from work-intake as MASSIVE)                          │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│               PHASE 1: DOCUMENT UNKNOWNS                            │
│  List everything we don't know                                      │
│  Prioritize by: blocks other decisions                              │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│               PHASE 2: RESEARCH SPIKES                              │
│  Create issues for each unknown                                     │
│  Time-box investigations                                            │
│  Document findings in issues                                        │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│               PHASE 3: DECISION LOG                                 │
│  Record all decisions made                                          │
│  Document alternatives considered                                   │
│  Note constraints and trade-offs                                    │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│               PHASE 4: EPIC STRUCTURE                               │
│  Group deliverables into epics                                      │
│  Define dependencies between epics                                  │
│  Create epic tracking issues                                        │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│               PHASE 5: MILESTONE PLANNING                           │
│  Create delivery milestones                                         │
│  Assign epics to milestones                                         │
│  Establish order of work                                            │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
                    READY FOR IMPLEMENTATION
                    (via epic-management per epic)
```

## Phase 1: Document Unknowns

### Create Initiative Tracking Issue

```bash
gh issue create \
  --title "[Initiative] [NAME]: Architecture & Planning" \
  --label "initiative,planning" \
  --body "## Initiative: [NAME]

## Original Request
[The original user request verbatim]

## Goal
[What success looks like at the highest level]

## Current Understanding
[What we know so far]

## Unknowns (To Be Investigated)

### Critical Unknowns (Block Architecture)
- [ ] Unknown 1: [Question]
- [ ] Unknown 2: [Question]

### Important Unknowns (Block Implementation)
- [ ] Unknown 3: [Question]
- [ ] Unknown 4: [Question]

### Nice-to-Know (Inform Decisions)
- [ ] Unknown 5: [Question]

## Research Spikes
[Will be populated as spikes are created]

## Decisions Log
[Will be populated as decisions are made]

## Epic Structure
[Will be populated after research]

## Milestones
[Will be populated after epic structure]

---
**Status:** 🔬 Investigating
**Last Updated:** [DATE]
**Context Recovery:** Read this issue + linked spikes + decision log"
```

### Unknown Categories

| Category | Definition | Action |
|----------|------------|--------|
| **Critical** | Blocks architecture decisions | Research spike immediately |
| **Important** | Blocks implementation | Research spike before epic |
| **Nice-to-Know** | Informs decisions | Research during implementation |

## Phase 2: Research Spikes

### Create Spike Issues

For each critical/important unknown:

```bash
gh issue create \
  --title "[Spike] [INITIATIVE]: [UNKNOWN QUESTION]" \
  --label "spike,research,initiative-[NAME]" \
  --body "## Research Spike

**Parent Initiative:** #[INITIATIVE_NUMBER]
**Unknown:** [The question we're answering]
**Time-box:** [X hours/days]

## Investigation Plan
1. [ ] Check existing codebase for [X]
2. [ ] Review documentation for [Y]
3. [ ] Test/prototype [Z]
4. [ ] Document findings

## Findings
[To be filled during research]

## Recommendation
[To be filled after research]

## Decision Needed
[What decision this enables]

---
**Status:** 🔬 Investigating
**Started:** [DATE]
**Due:** [DATE]"
```

### Spike Execution

Each spike should:
1. **Time-box** - Don't over-investigate
2. **Document as you go** - Findings in the issue
3. **Conclude with recommendation** - Clear next step
4. **Update initiative** - Mark unknown as resolved

### Spike Completion

```bash
# Update spike issue with findings
gh issue comment [SPIKE_NUMBER] --body "## Findings Summary

**Answer:** [The answer to the unknown]

**Evidence:**
- [Finding 1]
- [Finding 2]

**Recommendation:** [Recommended approach]

**Confidence:** [High/Medium/Low]

**Trade-offs:**
- Pro: [X]
- Con: [Y]"

# Close spike
gh issue close [SPIKE_NUMBER]

# Update initiative issue
gh issue comment [INITIATIVE_NUMBER] --body "## Spike Complete: #[SPIKE_NUMBER]

**Unknown:** [Question]
**Answer:** [Answer summary]
**Decision enabled:** [What we can now decide]"
```

## Phase 3: Decision Log

### Record Every Decision

In the initiative issue, maintain a decision log:

```markdown
## Decisions Log

### Decision 1: [Topic]
**Date:** [DATE]
**Context:** [Why this decision was needed]
**Options Considered:**
1. Option A: [Description] - [Pros/Cons]
2. Option B: [Description] - [Pros/Cons]
3. Option C: [Description] - [Pros/Cons]

**Decision:** Option [X]
**Rationale:** [Why this option]
**Implications:** [What this means for implementation]
**Spike:** #[SPIKE_NUMBER] (if applicable)

---

### Decision 2: [Topic]
...
```

### Decision Template

Use this for each decision:

```markdown
### Decision: [TITLE]
**Date:** YYYY-MM-DD
**Decided by:** [Agent/Human/Both]

**Context:**
[Why this decision was needed now]

**Options:**
| Option | Pros | Cons |
|--------|------|------|
| A: [X] | [+] | [-] |
| B: [Y] | [+] | [-] |

**Decision:** [Chosen option]

**Rationale:**
[Why this option was chosen]

**Reversibility:** [Easy/Hard/Irreversible]

**Related:**
- Spike: #[N] (if applicable)
- Depends on: Decision [X]
- Enables: Decision [Y]
```

## Phase 4: Epic Structure

### Identify Epics

After research spikes complete, group work into epics:

```markdown
## Epic Structure

### Epic 1: [NAME]
**Goal:** [What this epic delivers]
**Dependencies:** None
**Estimated Issues:** [X-Y]
**Key Delivera