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