---
roadcrew_template_name: "guide-planning.md"
roadcrew_template_type: "command"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-29"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
execution_mode: "auto-execute"
---

# guide-planning

Guide planning workflow from feature conception to release documentation. Orchestrates ANALYSIS → PLANNING phases with narrative scaffolding and release definition generation.

> **Execution:** Runs immediately. No approval needed between phases.

**Cost Optimization:** Concise, action-first responses with script-first validation and automatic file organization.

## Usage

```
/guide-planning
```

## What This Command Does

Creates a guided workflow to move from feature conception to structured release planning:

1. **Feature Naming & Description** - Collect feature concept and narrative
2. **Narrative Scaffolding** - Generate folder structure with skeleton files
3. **Current Release Validation** - Check prerequisites and provide recommendations
4. **Release Documentation** - Generate BRD → PRD → Spec using create-release-docs
5. **Release Definition** - Format and insert definition into future-releases.md
6. **Optional Release Advancement** - Offer advancement with confirmation

**Workflow:** Conception → Analysis → Planning → Documentation → Release Queue

## Steps

### Phase 1: Feature Conception 📋

**📁 Context Setup:** Close all unrelated files.

#### Task 1: Feature Naming and Description 👤

**Human Action Required:**
- Feature name (lowercase, kebab-case: e.g., `api-versioning`, `payment-redesign`)
- Feature description (1-2 sentences: what problem it solves)
- Feature category (enhancement, feature, refactor, infrastructure)

**Input Example:**
```
Name: api-versioning
Description: Implement API version management with backwards compatibility strategy
Category: infrastructure
```

**Output:** Feature ID and description captured

---

#### Task 2: Narrative Template Selection 👤

**Human Action Required:**
- Review available narrative templates in `memory-bank/requirements/source-docs/`
- Select template type:
  - `freemium` - For tier/licensing related features
  - `command-cleanup` - For command system improvements
  - `submodule-isolation` - For deployment/packaging features
  - `license-enforcement` - For license/compliance features
  - `classification` - For classification system improvements
- If none match, select `generic-feature` (template will be created)

**Output:** Template type selected

---

### Phase 2: Narrative Scaffolding 🏗️

**📁 Context Setup:** Keep feature details visible.

#### Task 3: Generate Narrative Structure 🤖

**AI Action - Script Phase:**

```bash
# Scaffold narrative folder structure
mkdir -p memory-bank/requirements/source-docs/{{FEATURE_ID}}
```

**AI Action - Template Generation:**

Create skeleton files in `memory-bank/requirements/source-docs/{{FEATURE_ID}}/`:

```
├── 00-OVERVIEW.md           # Feature overview and business context
├── 01-ANALYSIS.md          # Analysis findings (populated by /analyze-repo)
├── 02-PLANNING.md          # Planning decisions and dependencies
├── 03-IMPLEMENTATION.md    # Implementation strategy and sequencing
├── 04-TESTING.md           # Testing strategy and coverage goals
└── README.md               # Narrative index and status
```

**File Content Pattern:**

```markdown
---
feature_id: {{FEATURE_ID}}
feature_name: {{FEATURE_NAME}}
status: 🟡 PLANNING
created: {{DATE}}
related_epics: []
---

# {{FEATURE_NAME}} - {{SECTION_NAME}}

[Placeholder content for this section]
```

**Output:** Narrative folder scaffolded with skeleton files ✅

---

### Phase 3: Current Release Check 📊

**📁 Context Setup:** Open `memory-bank/releases/current-release.md` alongside narrative files.

#### Task 4: Validate Current Release Status 👤

**Human Action Required:**
- Open `memory-bank/releases/current-release.md`
- Check: Are all current epics/issues complete?
- Answer: Can we add a new epic to future-releases or should we wait for next cycle?

**Script Phase (AI):**

```bash
# Check current release completion status
grep -c "✅" memory-bank/releases/current-release.md
grep -c "⏳" memory-bank/releases/current-release.md
```

**AI Output Format:**

```
📊 Current Release Status (v1.6.5):
- ✅ Complete: N epics
- ⏳ Pending: N epics
- 🔴 Blocked: N issues

→ Recommendation: [Add to future-releases | Hold until v1.6.5 completes | Discuss scope]
```

**Output:** Release status confirmed and recommendation provided

---

### Phase 4: Release Documentation 📝

**📁 Context Setup:** Close narrative files. Open milestones files and feature description.

#### Task 5: Collect BRD/PRD/Spec Intent 👤

**Human Action Required:**

Answer planning questions:

1. **Business Context:**
   - Why build this? (market need, user request, strategic priority)
   - Who benefits? (target users, segments)
   - Success metric (how do we measure success?)

2. **Product Requirements:**
   - Main user stories (3-5 key scenarios)
   - Acceptance criteria (what defines "done"?)
   - Out of scope (what are we NOT doing?)

3. **Technical Approach:**
   - High-level architecture (new module? existing update?)
   - Dependencies (external services, internal components)
   - Estimated complexity (1-3 hours, 4-8 hours, 9+ hours)

**Output:** BRD/PRD/Spec intent captured

---

#### Task 6: Generate Release Documentation 🤖

**AI Action:**

Run create-release-docs to generate BRD → PRD → Spec:

```bash
/create-release-docs --feature {{FEATURE_ID}} --from-narrative
```

**What This Does:**
- Reads `memory-bank/requirements/source-docs/{{FEATURE_ID}}/00-OVERVIEW.md`
- Uses BRD → PRD → Spec templates from `.roadcrew/templates/`
- Generates three documents:
  - `memory-bank/requirements/brds/{{FEATURE_ID}}-brd.md`
  - `memory-bank/requirements/prds/{{FEATURE_ID}}-prd.md`
  - `memory-bank/requirements/specs/{{FEATURE_ID}}-spec.md`
- Updates narrative README with links to generated docs
- Validates cross-references between documents

**Output Format:**

```
✅ Release Documentation Generated:
- BRD: memory-bank/requirements/brds/{{FEATURE_ID}}-brd.md
- PRD: memory-bank/requirements/prds/{{FEATURE_ID}}-prd.md
- Spec: memory-bank/requirements/specs/{{FEATURE_ID}}-spec.md

Next: Review and adjust if needed, then proceed to Task 7
```

**If validation fails:**
```
❌ Cross-reference validation failed:
- [Error 1]
- [Error 2]

Suggested fixes: [list]
```

---

#### Task 7: Validate Generated Documentation 👤

**Human Action Required:**
- Review generated BRD/PRD/Spec files
- Check: Are requirements clear and complete?
- Adjust: Edit files as needed for clarity and accuracy
- Confirm: All three documents aligned

**Output:** Documentation validated and ready for release queue

---

### Phase 5: Release Definition 📋

**📁 Context Setup:** Keep `memory-bank/releases/future-releases.md` open. Keep generated docs nearby.

#### Task 8: Generate Release Definition 🤖

**AI Action:**

Create release definition following `future-releases.md` format:

```markdown
## EPIC: {{FEATURE_NAME}} (Epic #TBD)

**Status**: 🟡 PENDING
**Related Docs**:
- BRD: [memory-bank/requirements/brds/{{FEATURE_ID}}-brd.md](../brds/{{FEATURE_ID}}-brd.md)
- PRD: [memory-bank/requirements/prds/{{FEATURE_ID}}-prd.md](../prds/{{FEATURE_ID}}-prd.md)
- Spec: [memory-bank/requirements/specs/{{FEATURE_ID}}-spec.md](../specs/{{FEATURE_ID}}-spec.md)
- Narrative: [memory-bank/requirements/source-docs/{{FEATURE_ID}}/](../narratives/{{FEATURE_ID}}/)

**Description**: [2-3 sentence description from PRD overview]

**Key Goals**:
- [Goal 1 from PRD]
- [Goal 2 from PRD]
- [Goal 3 from PRD]

**Success Criteria**:
- [ ] Criterion 1 from Spec § 6.1
- [ ] Criterion 2 from Spec § 6.1
- [ ] Criterion 3 from Spec § 6.1

**Estimated Effort**: [X-Y hours]

**Dependencies**: [List or "None"]

---

### Child Issues

1. [Issue template from Spec § 5.2 Issue Breakdown]
2. [Issue template from Spec § 5.2 Issue Breakdown]
3. [etc.]
```

**Output:** Release definition formatted and ready to insert

---

#### Task 9: Insert into Release Queue 👤

**Human Action Required:**

1. Open `memory-bank/releases/future-releases.md`
2. Scroll to appropriate section (e.g., "v1.7.0", "Backlog")
3. Copy formatted release definition from Task 8
4. Paste into future-releases.md
5. Save file

**Output:** Epic definition added to release queue ✅

---

### Phase 6: Optional Release Advancement 🚀

**📁 Context Setup:** Keep future-releases.md and narrative index visible.

#### Task 10: Review Completed Epic 👤

**Human Action Required:**

- Does the new epic need to move to current-release.md immediately?
- Or should it stay in future-releases.md until next cycle?

**Decision Points:**
- ✅ **Add to current release** if: Strategic priority, no blocking dependencies, team capacity available
- ⏳ **Keep in future-releases** if: Can wait for next release cycle, blocking dependencies exist, team at capacity

**Output:** Advancement decision made

---

#### Task 11: Optional Advancement to Current Release 🤖

**If User Selected "Add to Current Release":**

1. Copy epic definition from future-releases.md
2. Paste into `memory-bank/releases/current-release.md` → Epics section
3. Update status to "🟡 PENDING"
4. Add to epic checklist: `- [ ] Epic: {{FEATURE_NAME}}`
5. Update `current-release.md` metrics (total epics, total issues count)

**If User Selected "Keep in Future Releases":**

Skip this task - epic stays in future-releases.md for next cycle.

**Output:** Epic positioned in release timeline

---

## Complete Workflow Example

```
User: /guide-planning

AI: 📋 Feature Planning Guide

TODO (11 tasks, 7 human + 4 AI/script):
- [ ] 👤 Task 1: Feature naming & description
- [ ] 👤 Task 2: Narrative template selection
- [ ] 🤖 Task 3: Scaffold narrative structure
- [ ] 👤 Task 4: Validate current release status
- [ ] 👤 Task 5: Collect BRD/PRD/Spec intent
- [ ] 🤖 Task 6: Generate release documentation
- [ ] 👤 Task 7: Validate generated docs
- [ ] 🤖 Task 8: Generate release definition
- [ ] 👤 Task 9: Insert into future-releases.md
- [ ] 👤 Task 10: Review advancement decision
- [ ] 🤖 Task 11: Optional advancement

📁 Context: Close all files. Task 1 ready?

---

User: Feature name: notification-system
Description: Real-time notification system with user preferences
Category: feature

AI: ✅ Feature captured: notification-system
📋 Task 2: Which narrative template? (freemium | command-cleanup | submodule-isolation | license-enforcement | classification | new)

---

User: template-type: freemium

AI: ✅ Template selected: freemium
🤖 Task 3: Scaffolding narrative structure...

✅ Narrative scaffolded:
- memory-bank/requirements/source-docs/notification-system/00-OVERVIEW.md
- memory-bank/requirements/source-docs/notification-system/01-ANALYSIS.md
- memory-bank/requirements/source-docs/notification-system/02-PLANNING.md
- memory-bank/requirements/source-docs/notification-system/03-IMPLEMENTATION.md
- memory-bank/requirements/source-docs/notification-system/04-TESTING.md
- memory-bank/requirements/source-docs/notification-system/README.md

📋 Task 4: Open memory-bank/releases/current-release.md, check completion status. Ready?

---

User: Current release 60% complete. No blocking items.

AI: 📊 Current Release Status (v1.6.5):
- ✅ Complete: 2/4 epics
- ⏳ Pending: 2/4 epics
- 🔴 Blocked: 0 issues

→ Recommendation: Can add to current release if priority, or hold for next cycle

📋 Task 5: Answer planning questions (business context, product requirements, technical approach). Ready?

---

User: [Answers planning questions - see Task 5 format above]

AI: ✅ Planning intent captured
🤖 Task 6: Generating release documentation...

✅ Release Documentation Generated:
- BRD: memory-bank/requirements/brds/notification-system-brd.md
- PRD: memory-bank/requirements/prds/notification-system-prd.md
- Spec: memory-bank/requirements/specs/notification-system-spec.md

📋 Task 7: Review generated docs, adjust as needed. Ready to proceed?

---

User: Docs look good. PRD needs one clarification on user preference limits.

AI: ✅ Confirmed. Edit memory-bank/requirements/prds/notification-system-prd.md § 2.1 → add user preference limit

🤖 Task 8: Generating release definition...

✅ Release Definition Generated (formatted for future-releases.md)

📋 Task 9: Open memory-bank/releases/future-releases.md, paste definition in v1.7.0 section, save. Ready?

---

User: Done. Definition added to v1.7.0 section.

AI: ✅ Epic added to future-releases.md

📋 Task 10: Should notification-system advance to current release, or stay in future-releases?
Options: add-to-current | keep-in-future

---

User: keep-in-future

AI: ✅ Epic positioned in v1.7.0 backlog

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ PLANNING COMPLETE

Epic: notification-system
Status: 🟡 PLANNING → Ready for v1.7.0
Location: memory-bank/releases/future-releases.md
Documentation: 
  - BRD: memory-bank/requirements/brds/notification-system-brd.md
  - PRD: memory-bank/requirements/prds/notification-system-prd.md
  - Spec: memory-bank/requirements/specs/notification-system-spec.md
  - Narrative: memory-bank/requirements/source-docs/notification-system/

Next Steps:
1. Gather team feedback on BRD/PRD
2. When ready for implementation, run: /scope-release (creates GitHub issues)
3. Then run: /autopilot {{EPIC_NUMBER}} (implements epic)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## When to Use This Command

Use `/guide-planning` when:
- Starting a new feature from conception
- Need guided planning workflow with documentation generation
- Want narrative scaffolding and release definition automatically created
- Team needs alignment on BRD/PRD/Spec before implementation
- Planning feature for future release cycle

Skip `/guide-planning` when:
- Feature already has documentation
- Quick hotfix or patch (use direct edits instead)
- Experienced with manual process and prefer to skip steps