doit.roadmapit

Prompt file imported from seanbarlow/theme-switcher (.claude/commands/doit.roadmapit.md). Fill in {{arguments}} before use. Copyright stays with the author.

User Input

{{arguments}}

You MUST consider the user input before proceeding (if not empty).

Load Project Context

Before proceeding, load the project context to inform your responses:

doit context show

If the command fails or doit is not installed: Continue without context, but note that alignment with project principles cannot be verified.

Use loaded context to:

• Reference constitution principles when making decisions (constitution is in context)
• Review completed_roadmap for historical context (already loaded)
• Identify connections to related specifications

Note: Roadmap content is intentionally NOT loaded by context show for this command (to avoid circular reference when modifying). Read roadmap.md directly for modification.

DO NOT read these files again (already in context above):

• .doit/memory/constitution.md - principles are in context
• .doit/memory/completed_roadmap.md - history is in context

Legitimate explicit reads (for modification):

• .doit/memory/roadmap.md - must read to modify
• README.md - for project description (if no constitution)
• package.json or pyproject.toml - for project metadata

Code Quality Guidelines

Before generating or modifying code:

1. Search for existing implementations - Use Glob/Grep to find similar functionality before creating new code
2. Follow established patterns - Match existing code style, naming conventions, and architecture
3. Avoid duplication - Reference or extend existing utilities rather than recreating them
4. Check imports - Verify required dependencies already exist in the project

Artifact Storage

• Temporary scripts: Save to .doit/temp/{purpose}-{timestamp}.sh (or .py/.ps1)
• Status reports: Save to specs/{feature}/reports/{command}-report-{timestamp}.md
• Create directories if needed: Use mkdir -p before writing files
• Note: .doit/temp/ is gitignored - temporary files will not be committed

Outline

This command creates or updates the project roadmap at .doit/memory/roadmap.md. The roadmap captures high-level requirements prioritized by business value, deferred items, and project vision.

1. Parse Command Arguments

Extract the operation and details from {{arguments}}:

If no arguments provided or unrecognized pattern, proceed to step 2 for detection.

2. Check for Existing Roadmap

Check if .doit/memory/roadmap.md exists:

• If NOT exists: Proceed to Step 3 (Create Workflow)
• If exists: Proceed to Step 4 (Update Workflow)

3. Create Workflow (New Roadmap)

3.1 Ensure Directory Exists

mkdir -p .doit/memory

3.2 Gather Project Context

Use project context already loaded from doit context show:

• Constitution principles and tech stack (already in context)
• Completed roadmap history (already in context)

If constitution is not available, read these files for project metadata:

• README.md - Project description
• package.json or pyproject.toml - Project metadata

3.3 Ask Clarifying Questions

Present questions to establish roadmap foundation. Use the user's input (if provided) as context:

Question 1: Project Vision

What is the primary goal or vision for this project?

Based on your input "[USER_INPUT]", I understand the project is about [INTERPRETATION].

Please confirm or provide a more detailed vision statement.

Question 2: Initial Priority Items

What are the most critical features or requirements for your MVP?

Suggested based on your description:

• [SUGGESTION_1]
• [SUGGESTION_2]

Which of these are correct? What would you add or change?

Question 3: Known Constraints

Are there any constraints or limitations to consider?

Options: A. Timeline constraints (specific deadline) B. Technical constraints (must use specific tech) C. Resource constraints (limited team/budget) D. No significant constraints E. Custom (please specify)

3.4 Build Roadmap Structure

Using the gathered information, create the roadmap:

1. Load template from .doit/templates/roadmap-template.md
2. Replace [PROJECT_NAME] with project name from constitution or package metadata
3. Replace [DATE] with current date
4. Replace [PROJECT_VISION] with the confirmed vision statement
5. Populate priority sections based on user's answers:
   • Add confirmed critical items to P1
   • Add important but not blocking items to P2
   • Add nice-to-have items to P3/P4
6. Leave Deferred Items empty for new roadmaps

3.5 Write Roadmap

Write the populated roadmap to .doit/memory/roadmap.md

3.6 Offer Enhancement Suggestions

After creating the roadmap, proceed to Step 6 (AI Suggestions).

4. Update Workflow (Existing Roadmap)

4.1 Load Current Roadmap

Read .doit/memory/roadmap.md and parse:

• Current vision statement
• All items in P1, P2, P3, P4 sections with their status
• All deferred items
• Last updated date

4.2 Display Current State

Show the user the current roadmap state:

## Current Roadmap State

**Vision**: [Current vision statement]
**Last Updated**: [Date]

### Active Items
| Priority | Item | Feature Branch | Status |
|----------|------|----------------|--------|
| P1 | [item] | [branch-ref] | [ ] |
| P2 | [item] | [branch-ref] | [ ] |
...

### Deferred Items
| Item | Original Priority | Reason |
|------|-------------------|--------|
...

4.3 Handle Specific Operations

Based on the parsed operation from Step 1:

Add Operation (add [item]):

1. Ask: "What priority should this item have? (P1/P2/P3/P4)"
2. Ask: "What's the business rationale for this priority?"
3. Ask: "Is there a feature branch reference? (e.g., [###-feature-name])"
4. Add the item to the appropriate section

Defer Operation (defer [item]):

1. Search for the item in active sections
2. If not found: List available items and ask user to select
3. If found: Ask "What's the reason for deferring?"
4. Move item to Deferred section with original priority and reason

Reprioritize Operation (reprioritize):

1. List all active items with current priorities
2. Ask: "Which items need priority changes?"
3. For each item to change:
   • Show current priority
   • Ask for new priority (P1/P2/P3/P4)
   • Ask for rationale for the change
4. Update items in their new sections

Sync Milestones Operation (sync-milestones or sync-milestones --dry-run):

1. Execute the milestone sync command:

   doit roadmapit sync-milestones [--dry-run]

2. The command will:

   • Create GitHub milestones for each priority level (P1-P4) if they don't exist
   • Assign roadmap epics to their corresponding priority milestones
   • Display a summary of changes made

3. After sync completes, show:

   • Milestones created count
   • Epics assigned count
   • Link to view milestones on GitHub

4. Complete this operation - Do not proceed to other steps

Interactive Update (no specific operation):

1. Ask: "What would you like to do?"
   • A. Add a new item
   • B. Defer an item
   • C. Reprioritize items
   • D. Update the vision statement
   • E. Mark an item as complete (moves to completed_roadmap.md)
   • F. Sync priorities to GitHub milestones
2. Execute the selected operation

4.4 Preserve Unmodified Content

When updating the roadmap:

• Keep all items not explicitly changed
• Maintain existing rationales unless updated
• Preserve feature branch references
• Update only the Last Updated date

4.5 Write Updated Roadmap

Write the modified roadmap back to .doit/memory/roadmap.md

4.6 Offer Enhancement Suggestions

After updating, proceed to Step 6 (AI Suggestions).

5. Handle Edge Cases

5.1 Malformed Roadmap

If existing roadmap cannot be parsed:

1. Create backup: mv .doit/memory/roadmap.md .doit/memory/roadmap.md.bak
2. Notify user: "The existing roadmap appears to be malformed. A backup has been created."
3. Try to extract any readable content
4. Offer to create fresh roadmap incorporating salvaged content

5.2 Item Not Found (for defer/update)

If specified item cannot be found:

1. List all current items in a table
2. Ask user to select from the list or provide exact item text
3. Use fuzzy matching to suggest closest matches

5.3 Conflicting Priorities

If user assigns multiple P1 items:

1. Show warning: "You have [N] P1 items. P1 should be reserved for truly critical items."
2. Ask: "Would you like to compare these items to determine which is most critical?"
3. If yes, present pairwise comparison for each P1 item

6. AI Enhancement Suggestions

After any create or update operation, analyze the roadmap and project context to suggest enhancements.

6.1 Gather Context

Use context already loaded from doit context show:

• Constitution principles (already in context)
• Completed roadmap history (already in context)
• Current roadmap items and gaps (from roadmap file read in step 4.1)

6.2 Generate Suggestions

Based on context, generate 2-5 complementary feature suggestions:

## Enhancement Suggestions

Based on your roadmap and project context, here are some features you might consider:

### Suggestion 1: [Feature Name]
**Rationale**: [Why this complements existing items]
**Suggested Priority**: P[N]
**Aligns with**: [Related existing item or principle]

### Suggestion 2: [Feature Name]
...

---

**Actions**:
- Type the suggestion number to add it (e.g., "1" or "1, 3")
- Type "skip" to finish without adding suggestions
- Type "modify [N]" to customize a suggestion before adding

6.3 Handle Suggestion Response

• If user selects suggestions: Add them to the appropriate priority sections
• If user modifies: Apply customizations then add
• If user skips: Complete without changes

7. Completion Report

Output a summary of changes:

## Roadmap Update Complete

**File**: `.doit/memory/roadmap.md`
**Operation**: [Create/Add/Defer/Reprioritize]
**Date**: [Current date]

### Changes Made
- [List of specific changes]

### Current Statistics
| Priority | Count |
|----------|-------|
| P1 | [N] |
| P2 | [N] |
| P3 | [N] |
| P4 | [N] |
| Deferred | [N] |

### Next Steps
- Run `/doit.specit` to create specs for top priority items
- Run `/doit.roadmapit` again to continue updating
- Review completed items in `.doit/memory/completed_roadmap.md`

Key Rules

• Always preserve existing content when updating
• Ask clarifying questions before making changes
• Provide AI suggestions after every operation
• Use feature branch references [###-feature-name] for traceability
• Maintain maximum 3-5 P1 items (truly critical only)
• Back up malformed roadmaps before recreating

Error Recovery

GitHub API Authentication Failure

The roadmap could not be synced because GitHub authentication is invalid.

ERROR | If GitHub API calls fail during roadmap sync:

1. Check your authentication: gh auth status
2. If expired or invalid, re-authenticate: gh auth login
3. Verify repository access: gh repo view
4. Retry: re-run /doit.roadmapit
5. Verify: gh issue list --limit 5 confirms API access is working

Prevention: Run gh auth status before starting roadmap operations

If the above steps don't resolve the issue: proceed with local-only roadmap updates — GitHub sync can be done later.

Merge Conflict in Roadmap File

The roadmap file has conflicting changes from concurrent edits.

ERROR | If the roadmap file has merge conflicts:

1. Open the roadmap file and look for conflict markers (<<<<<<<, =======, >>>>>>>)
2. Resolve conflicts by choosing the correct content for each section
3. After resolving, stage the file: git add .doit/memory/roadmap.md
4. Verify: cat .doit/memory/roadmap.md | grep -c "<<<<<<" returns 0

Prevention: Pull latest changes before editing the roadmap: git pull

If the above steps don't resolve the issue: back up your changes, reset the file to the remote version, and manually re-apply your updates.

Priority Conflict or Duplicate Items

The roadmap contains duplicate entries or conflicting priority assignments.

WARNING | If duplicate or conflicting roadmap items are detected:

1. Review the roadmap for duplicate entries: check for items with similar names
2. Merge duplicates by combining their descriptions and keeping the higher priority
3. Resolve priority conflicts by reviewing the project goals and timeline
4. Re-run /doit.roadmapit to validate the updated roadmap
5. Verify: no duplicate items appear in the roadmap output

Prevention: Review existing roadmap items before adding new ones to avoid duplicates

If the above steps don't resolve the issue: manually edit the roadmap file to remove duplicates and set clear priorities.

Next Steps

After completing this command, display a recommendation section based on the outcome:

On Success (roadmap created or updated)

Display the following at the end of your output:

---

## Next Steps

**Roadmap updated!**

**Recommended**: Run `/doit.specit [top priority item]` to create a specification for your highest priority feature.

**Alternative**: Run `/doit.roadmapit add [item]` to add more items to the roadmap.

On Item Added

If a new item was added to the roadmap:

---

## Next Steps

**Item added to roadmap!**

**Recommended**: Run `/doit.specit [item description]` to create a specification for this item.

**Alternative**: Run `/doit.roadmapit reprioritize` to review and adjust priorities.