/iterate Command Workflow

`/iterate` Command Workflow

Overview

The /iterate command is a dedicated capability of the planning-agent that allows users to update Epic content based on new information that emerges during the design phase. It provides a structured way to incorporate decisions from Teams chats, meeting transcripts, and direct input while tracking open questions and blockers.

Architecture

/iterate uses a hybrid architecture combining a command (orchestration) with specialized skills (logic execution):

Command Layer (/iterate):

User-facing workflow orchestrator
Handles conversational flow and user prompts
Coordinates the overall iteration process
Shows previews and gets user confirmation
Manages state and decision flow

Skill Layer (reusable components):

meeting-parser - Parses meeting transcripts (Fireflies, etc.), extracts decisions and open questions
teams-chat-parser - Parses Teams chat exports, extracts decisions and open questions
epic-updater - Updates Epic content files (PRD, User Stories, RACI) with validated changes
refinement-tracker - Manages REFINEMENT.md (adds questions, logs decisions, marks resolved)

This separation enables:

Reusability: Other commands can leverage these skills (e.g., /track updating Epics from Jira)
Modularity: Each skill has a single, testable responsibility
Maintainability: Logic is isolated and easier to update independently

Context & Purpose

Epic content is initially created during the planning phase with the best available information. However, much of the substantive detail and end-user requirements cannot be fully determined until the design phase. The design team needs user stories to begin work, but these stories are then refined and detailed during design before they reach the development phase.

/iterate handles this post-creation refinement process - updating already-created Epic content as it evolves through design.

Epic Content Definition

Throughout this document, “Epic content” refers to all key documents for each Epic:

PRD (Product Requirements Document)
User Stories
Idea Brief
RACI Matrix
REFINEMENT.md (tracks ongoing unknowns and decisions)

Command Flow

1. Initial Invocation

/iterate {epic-key}

Example: /iterate TP-1234

The planning-agent will:

Locate the Epic within the initiative structure (.trilogy/initiatives/TP-XXXX-initiative/TP-YYYY-epic/)
Load existing Epic content (PRD, User Stories, RACI, REFINEMENT.md)
Present an overview of current Epic state

2. Iteration Method Selection

Agent prompts user to choose:

Direct iteration: User directly tells agent what to update
Indirect iteration: User provides external content (Teams chat or meeting transcript)

Direct Iteration Path

Flow

User describes desired changes verbally
Planning-agent compares requested changes against current Epic content (PRD, User Stories, RACI, REFINEMENT.md)
Planning-agent proposes specific updates showing how they would appear in each affected file
User reviews and confirms
Planning-agent invokes skills to apply changes:
- epic-updater skill: Updates PRD, User Stories, RACI files
- refinement-tracker skill: Logs decisions in REFINEMENT.md
- Jira sync using existing mechanisms
Planning-agent confirms completion and shows summary of changes made

Example

User: "Add requirement for multi-currency support in invoices"

Agent: "I'll add this to the Epic content. Here's how it will appear:

**PRD Updates:**
- Section 3.2: Add 'Multi-currency support for international clients'

**User Stories Updates:**
- New story: 'As an admin, I want to configure supported currencies'

**RACI Updates:**
- Multi-currency configuration: Design team Responsible, Product Owner Accountable

**REFINEMENT.md Updates:**
- Decision logged: Multi-currency support confirmed for international expansion

Confirm these changes?"

Indirect Iteration Path

File Type Selection

Agent prompts: Teams Chat or Meeting Transcript

Meeting Transcript Flow

Step 1: File Upload

User provides Fireflies meeting transcript
Planning-agent saves to Epic’s dumping ground folder: .trilogy/initiatives/TP-XXXX-initiative/TP-YYYY-epic/dumping-ground/meetings/

Step 2: Analysis Phase

Planning-agent invokes meeting-parser skill which:

Parses the meeting transcript
Extracts decided changes (clear decisions that can be immediately applied)
Extracts open questions (unresolved issues or blockers requiring resolution)
Returns structured output to the planning-agent

Output Format:

{
  "decisions": [
    {
      "decision": "Payment gateway: Stripe selected over PayPal",
      "context": "...",
      "impacts": ["PRD Section 3.2", "User Story US-005"]
    }
  ],
  "open_questions": [
    {
      "question": "Which service for international tax rules?",
      "context": "...",
      "impact": "Affects invoice calculation logic",
      "suggested_owner": "Tech Lead"
    }
  ]
}

Step 3: User Review - Decided Changes

Agent: "Found 3 decisions from the meeting:

1. Payment gateway: Stripe selected over PayPal
2. Webhook retry: Implement exponential backoff (3 attempts)
3. Multi-currency: Launch with USD, EUR, GBP only

Proposed Epic content updates:
[Shows specific changes to PRD, stories, brief]

Confirm these updates?"

Upon confirmation, planning-agent invokes skills:

epic-updater skill: Updates PRD, User Stories, RACI files with decided changes
refinement-tracker skill: Logs decisions in REFINEMENT.md “Decisions Made” section
Jira sync executed using existing sync procedures
Planning-agent confirms completion with summary

Step 4: User Review - Open Questions

Agent: "Found 2 open questions requiring resolution:

1. Tax calculation: Which service to use for international tax rules?
2. Currency conversion: Real-time rates or daily batch updates?

For each question, you can:
- Resolve now (provide answer → updates Epic content)
- Track as open question (adds to REFINEMENT.md and creates Jira Task blocker)

If user resolves now: Planning-agent invokes skills to apply resolution:

epic-updater skill: Incorporates answer into Epic content (PRD, User Stories, RACI as applicable)
refinement-tracker skill: Logs decision in REFINEMENT.md “Decisions Made” section
Jira sync executed
Planning-agent confirms completion

If tracking as open question: Planning-agent invokes skills to track the blocker:

refinement-tracker skill: Adds question to REFINEMENT.md “Unresolved Questions” section with:
- The question
- Impact on user stories/requirements
- Owner (who needs to answer)
- Checkbox for tracking resolution
Jira Task created under the Epic as blocker (using existing sync mechanisms)
epic-updater skill: Marks affected user stories as blocked if needed
Can be resolved later via another /iterate run

Step 5: Iterative Resolution

User can run /iterate {epic-key} again after blocker tasks are resolved to incorporate those answers into Epic content.

Teams Chat Export Flow

Differences from Meeting Transcript

Teams chat exports can be lengthy
May contain ongoing discussions spanning multiple days
Process similar to meeting transcript:
1. Upload chat export to dumping-ground/teams-chats/
2. Planning-agent invokes teams-chat-parser skill to extract decisions and open questions
3. Same review/confirmation flow
4. Planning-agent invokes epic-updater and refinement-tracker skills to update Epic content
5. Jira sync executed

Context Management Considerations

Teams chats are processed incrementally (see separate teams-chat-log-system.md documentation)
The /iterate command can reference the ongoing Teams chat log as context
Agent may ask: “Would you like to review recent Teams discussions from the log?”

File Storage Structure

.trilogy/initiatives/TP-XXXX-initiative/TP-YYYY-epic/
├── idea.md                         # Initial idea brief
├── PRD.md                          # Product Requirements Document
├── RACI.md                         # RACI matrix
├── REFINEMENT.md                   # Ongoing unknowns and decisions
├── USER-STORIES/
│   └── user-stories.csv            # User stories for Jira sync
└── dumping-ground/                 # All supporting materials
    ├── meetings/
    │   ├── 2025-01-15-kickoff.txt
    │   └── 2025-01-20-review.txt
    └── teams-chats/
        └── teams-chat-log.md       # Ongoing Teams discussion log

Key Design Principles

Planning-agent ownership: /iterate is a dedicated capability of the planning-agent for maintaining Epic content throughout the design phase
Always show before applying: User must review and confirm all Epic content changes
Track blockers systematically: Open questions are added to REFINEMENT.md and become Jira Task blockers if not immediately resolvable
Format consistency: Proposed changes shown in exact format they’ll appear in files
Use existing mechanisms: All file updates and Jira syncs use the same scripts/procedures from initial Epic creation
Comprehensive updates: Changes propagate to all affected Epic content (PRD, User Stories, RACI, REFINEMENT.md)
Iterative resolution: Support multiple /iterate runs to resolve questions over time as design progresses

Integration Points

With Planning-Agent Workflow

Uses existing initiative/epic file structure from planning-agent
Leverages existing Jira sync scripts/procedures established during Epic creation
Extends REFINEMENT.md usage from pre-creation unknowns to post-creation design refinements
Maintains consistency with planning-agent conventions for all file updates

With Jira

Syncs Epic content updates (description, stories, RACI, etc.) using existing sync procedures
Creates Task work items for open questions that become blockers
Updates Epic status based on blocker resolution
Marks affected user stories as blocked when dependencies exist

With Teams Chat Log

Can reference ongoing teams-chat-log.md as context source
Teams discussions automatically captured (see separate documentation)
/iterate can incorporate recent log entries without manual export

Future Enhancements (Not Yet Implemented)

Auto-suggest /iterate when Teams chat log shows significant decisions
Diff view showing before/after for Epic content changes
Support for other transcript formats (Zoom, Google Meet, etc.)
Batch processing multiple meeting transcripts at once

Skills Reference

`meeting-parser` Skill

Purpose: Parse meeting transcripts and extract structured decisions and open questions

Input: Meeting transcript text (Fireflies, Zoom, Google Meet, etc.)

Output: JSON with decisions[] and open_questions[] arrays

Used by: /iterate command (and potentially other commands needing meeting analysis)

`teams-chat-parser` Skill

Purpose: Parse Teams chat exports and extract structured decisions and open questions

Input: Teams chat export text

Output: JSON with decisions[] and open_questions[] arrays

Used by: /iterate command (and potentially other commands needing Teams chat analysis)

`epic-updater` Skill

Purpose: Update Epic content files (PRD, User Stories, RACI) with validated changes

Input: Epic location, changes to apply (structured format)

Output: Success/failure status, list of files modified

Used by: /iterate, /track (and potentially other commands that modify Epic content)

`refinement-tracker` Skill

Purpose: Manage REFINEMENT.md - add questions, log decisions, mark resolved

Input: Epic location, action (add_question, log_decision, mark_resolved), data

Output: Success/failure status, updated REFINEMENT.md state

Used by: /iterate, /stories (and potentially other commands managing refinement questions)

/jira-sync - Syncs Epics to/from Jira
/idea - Creates initial idea brief
/prd - Generates PRD from idea brief
/stories - Generates user stories from PRD (may use refinement-tracker skill)
/track - Updates Epic progress from Jira (may use epic-updater skill)
/link-chat - Links Teams chat to Epic (enables Teams chat log)

/iterate Command Workflow

/iterate Command Workflow

Overview

Architecture

Context & Purpose

Epic Content Definition

Command Flow

1. Initial Invocation

2. Iteration Method Selection

Direct Iteration Path

Flow

Example

Indirect Iteration Path

File Type Selection

Meeting Transcript Flow

Step 1: File Upload

Step 2: Analysis Phase

Step 3: User Review - Decided Changes

Step 4: User Review - Open Questions

Step 5: Iterative Resolution

Teams Chat Export Flow

Differences from Meeting Transcript

Context Management Considerations

File Storage Structure

Key Design Principles

Integration Points

With Planning-Agent Workflow

With Jira

With Teams Chat Log

Future Enhancements (Not Yet Implemented)

Skills Reference

meeting-parser Skill

teams-chat-parser Skill

epic-updater Skill

refinement-tracker Skill

Related Commands

`/iterate` Command Workflow

`meeting-parser` Skill

`teams-chat-parser` Skill

`epic-updater` Skill

`refinement-tracker` Skill