name	initiative-architecture
description	Use for MASSIVE work requests requiring multi-epic planning. Creates research spikes, documents all unknowns and decisions, builds resumable architecture documents, and structures work into epics and milestones.

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

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:

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:

Time-box - Don't over-investigate
Document as you go - Findings in the issue
Conclude with recommendation - Clear next step
Update initiative - Mark unknown as resolved

Spike Completion

# 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:

## 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:

### 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:

## Epic Structure

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

### Epic 2: [NAME]
**Goal:** [What this epic delivers]
**Dependencies:** Epic 1
**Estimated Issues:** [X-Y]
**Key Deliverables:**
- Deliverable C
- Deliverable D

### Epic 3: [NAME]
**Goal:** [What this epic delivers]
**Dependencies:** Epic 1, Epic 2
**Estimated Issues:** [X-Y]
**Key Deliverables:**
- Deliverable E

Create Epic Labels

# Create initiative label
gh label create "initiative-[NAME]" --color "6E40C9" \
  --description "Part of [INITIATIVE NAME] initiative"

# Create epic labels
gh label create "epic-[EPIC1-NAME]" --color "0E8A16" \
  --description "[Epic 1 description]"
gh label create "epic-[EPIC2-NAME]" --color "1D76DB" \
  --description "[Epic 2 description]"

Create Epic Tracking Issues

For each epic, use epic-management skill to create the epic structure.

Phase 5: Milestone Planning

Create Milestones

# Create milestones for delivery phases
gh api repos/{owner}/{repo}/milestones -X POST \
  -f title="[Initiative] Phase 1: [NAME]" \
  -f description="[Description of what Phase 1 delivers]" \
  -f due_on="YYYY-MM-DDTHH:MM:SSZ"

Assign Epics to Milestones

Milestone	Epics	Goal
Phase 1	Epic 1	[Foundation]
Phase 2	Epic 2, 3	[Core Features]
Phase 3	Epic 4	[Polish & Launch]

Resumability

Context Recovery Document

The initiative issue must always contain enough information for a fresh context to continue:

## Context Recovery

**To continue this initiative:**

1. Read this issue completely
2. Review open spikes: [links]
3. Review decision log above
4. Check current epic status: [links]
5. Current phase: [Investigation/Architecture/Implementation]
6. Next action: [Specific next step]

**Key files:**
- [Path to any architecture docs]
- [Path to any design docs]

**Key decisions made:**
1. [Decision 1 summary]
2. [Decision 2 summary]

Memory Integration

# Store initiative in knowledge graph
mcp__memory__create_entities([{
  "name": "Initiative-[NAME]",
  "entityType": "Initiative",
  "observations": [
    "Created: [DATE]",
    "Goal: [GOAL]",
    "Tracking Issue: #[NUMBER]",
    "Status: [STATUS]",
    "Epics: [LIST]",
    "Current Phase: [PHASE]"
  ]
}])

Example: Mobile Push Login Initiative

Request: "Add the ability for users to log in by clicking on a popup in their phone."

Phase 1: Unknowns

Critical:

Does a mobile app exist?
What push notification infrastructure exists?
What authentication system is in use?

Important:

What are security requirements for push auth?
What platforms need support (iOS/Android)?

Phase 2: Spikes Created

#201 - [Spike] Mobile App Status Investigation
#202 - [Spike] Push Notification Infrastructure Review
#203 - [Spike] Authentication System Analysis
#204 - [Spike] Push Authentication Security Requirements

Phase 3: Decisions Made

Mobile App: Need to build (doesn't exist) → React Native
Push Infrastructure: Use Firebase Cloud Messaging
Auth Flow: Magic link via push with JWT

Phase 4: Epic Structure

Epic: Mobile App Foundation (10 issues)
Epic: Push Notification System (8 issues)
Epic: Push Authentication Flow (12 issues)
Epic: Backend Auth Integration (6 issues)
Epic: Testing & Security Audit (5 issues)

Phase 5: Milestones

Phase 1: App + Push Infrastructure (Epics 1, 2)
Phase 2: Auth Implementation (Epics 3, 4)
Phase 3: Hardening (Epic 5)

Checklist

Created initiative tracking issue
Documented all unknowns
Categorized unknowns (Critical/Important/Nice-to-Know)
Created research spikes for critical unknowns
Completed research spikes
Documented all decisions with rationale
Defined epic structure
Created epic labels
Created milestones
Added context recovery section
Stored in knowledge graph

initiative-architecture

Install Skill

SKILL.md

Initiative Architecture

Overview

What is an Initiative?

The Architecture Process

Phase 1: Document Unknowns

Create Initiative Tracking Issue

Unknown Categories

Phase 2: Research Spikes

Create Spike Issues

Spike Execution

Spike Completion

Phase 3: Decision Log

Record Every Decision

Decision Template

Phase 4: Epic Structure

Identify Epics

Create Epic Labels

Create Epic Tracking Issues

Phase 5: Milestone Planning

Create Milestones

Assign Epics to Milestones

Resumability

Context Recovery Document

Memory Integration

Example: Mobile Push Login Initiative

Phase 1: Unknowns

Phase 2: Spikes Created

Phase 3: Decisions Made

Phase 4: Epic Structure

Phase 5: Milestones

Checklist