WIP: createdoc2
This commit is contained in:
Brian Madison
@@ -1,208 +1,65 @@
|
||||
# Create Document from Template (YAML Driven)
|
||||
|
||||
## Purpose
|
||||
## CRITICAL: Mandatory Elicitation Format
|
||||
|
||||
Create documents using YAML templates to drive interactive, section-by-section collaboration between AI and user.
|
||||
**When `elicit: true`, ALWAYS use this exact format:**
|
||||
|
||||
## Core Rules
|
||||
1. Present section content
|
||||
2. Provide detailed rationale (explain trade-offs, assumptions, decisions made)
|
||||
3. Present numbered options 1-9:
|
||||
- **Option 1:** Always "Proceed to next section"
|
||||
- **Options 2-9:** Select 8 methods from data/elicitation-methods
|
||||
- End with: "Select 1-9 or just type your question/feedback:"
|
||||
|
||||
1. **NEVER output YAML** - Final document contains only clean markdown
|
||||
2. **Interactive by default** - Work section-by-section unless YOLO mode
|
||||
3. **YAML template drives all behavior** - Parse template, follow instructions exactly
|
||||
4. **Apply elicitation when specified** - Use advanced elicitation for marked sections
|
||||
5. **Present sections cleanly** - Show content for review, then apply elicitation if flagged
|
||||
|
||||
## YAML Template Format
|
||||
|
||||
Templates are full YAML files with this structure:
|
||||
|
||||
```yaml
|
||||
template:
|
||||
id: template-name
|
||||
name: Human Readable Name
|
||||
output:
|
||||
format: markdown
|
||||
filename: docs/output.md
|
||||
title: "{{variable}} Document Title"
|
||||
|
||||
sections:
|
||||
- id: section-id
|
||||
title: Section Title
|
||||
instruction: "Detailed guidance for this section"
|
||||
elicit: true
|
||||
condition: "has ui"
|
||||
choices:
|
||||
repository: [Monorepo, Polyrepo]
|
||||
```
|
||||
**NEVER ask yes/no questions or use any other format.**
|
||||
|
||||
## Processing Flow
|
||||
|
||||
### 1. Parse YAML Template
|
||||
1. **Parse YAML template** - Load template metadata and sections
|
||||
2. **Set preferences** - Show current mode (Interactive), confirm output file
|
||||
3. **Process each section:**
|
||||
- Skip if condition unmet
|
||||
- Draft content using section instruction
|
||||
- Present content + detailed rationale
|
||||
- **IF elicit: true** → MANDATORY 1-9 options format
|
||||
- Save to file if possible
|
||||
4. **Continue until complete**
|
||||
|
||||
- Load template metadata (id, name, output settings)
|
||||
- Extract `sections` list (required)
|
||||
- Note any section with `elicit: true`, `condition: "text"`, `choices`, or `repeatable: true`
|
||||
- Handle nested sections for complex document structure
|
||||
- For repeatable sections, use the template structure defined in the section
|
||||
## Detailed Rationale Requirements
|
||||
|
||||
### 2. Set User Preferences
|
||||
When presenting section content, ALWAYS include rationale that explains:
|
||||
|
||||
**Interaction Mode:** Currently Interactive (type `#yolo` to toggle to YOLO mode)
|
||||
- Trade-offs and choices made (what was chosen over alternatives and why)
|
||||
- Key assumptions made during drafting
|
||||
- Interesting or questionable decisions that need user attention
|
||||
- Areas that might need validation
|
||||
|
||||
**Output Location:** Confirm file output location from template (e.g., `docs/prd.md`). If environment doesn't support file writing (like web UI), will keep content in chat until complete.
|
||||
## Elicitation Results Flow
|
||||
|
||||
### 3. Process Each Section
|
||||
After user selects elicitation method (2-9):
|
||||
|
||||
For each section in order:
|
||||
1. Execute method from data/elicitation-methods
|
||||
2. Present results with insights
|
||||
3. Offer options:
|
||||
- **1. Apply changes and update section**
|
||||
- **2. Return to elicitation menu**
|
||||
- **Free text: Questions about this elicitation**
|
||||
|
||||
**Interactive Mode:**
|
||||
## YOLO Mode
|
||||
|
||||
1. **Skip if condition unmet** - If `condition: "has ui"` and project has no UI, skip entirely
|
||||
2. **Draft section content** - Use section `instruction` and handle choices/variables
|
||||
3. **Handle repeatable sections** - If section has `repeatable: true`, generate multiple instances based on nested structure
|
||||
4. **Present to user** - Show clean section content for review
|
||||
5. **Provide detailed rationale** - Include thoughtful analysis highlighting (for example):
|
||||
- Interesting or questionable decisions made
|
||||
- Trade-offs and choices (what was chosen over alternatives and why)
|
||||
- Areas that might need user attention or validation
|
||||
- Key assumptions made during drafting
|
||||
6. **Get user feedback** - Accept changes or proceed
|
||||
7. **Apply elicitation if specified** - If `elicit: true`, present standardized 1-9 options:
|
||||
- Option 1: Always "Proceed to next section"
|
||||
- Options 2-9: MUST select 8 relevant methods from data/elicitation-methods (never create new ones)
|
||||
- Include "Select 1-9 or just type your question/feedback:" to allow free chat
|
||||
8. **Process elicitation results** - After user selects elicitation method, present results with options:
|
||||
- Option 1: "Apply suggested changes and update section"
|
||||
- Option 2: "Return to elicitation selection (2-9 options)"
|
||||
- Free text: "Ask questions or follow-ups about this elicitation"
|
||||
- Allow multiple elicitation rounds on same section
|
||||
9. **Save to document** - If document-as-we-go mode, append approved content to file
|
||||
10. **Continue to next section**
|
||||
User can type `#yolo` to toggle to YOLO mode (process all sections at once).
|
||||
|
||||
**YOLO Mode:**
|
||||
## CRITICAL REMINDERS
|
||||
|
||||
- Process all sections at once, then present complete document
|
||||
**❌ NEVER:**
|
||||
|
||||
### 4. Final Output
|
||||
- Ask yes/no questions for elicitation
|
||||
- Use any format other than 1-9 numbered options
|
||||
- Create new elicitation methods
|
||||
|
||||
- Present complete document with clean markdown only
|
||||
- Save to file if specified
|
||||
- No YAML, no template syntax, no processing instructions
|
||||
**✅ ALWAYS:**
|
||||
|
||||
## Section Types
|
||||
|
||||
**Simple section:**
|
||||
|
||||
```yaml
|
||||
- id: requirements
|
||||
title: Requirements
|
||||
instruction: "Draft functional (FR1, FR2...) and non-functional (NFR1, NFR2...) requirements"
|
||||
```
|
||||
|
||||
**Section with elicitation:**
|
||||
|
||||
```yaml
|
||||
- id: technical-assumptions
|
||||
title: Technical Assumptions
|
||||
instruction: "Gather technical decisions that will guide the Architect"
|
||||
elicit: true
|
||||
choices:
|
||||
architecture: [Monolith, Microservices, Serverless]
|
||||
```
|
||||
|
||||
**Conditional section:**
|
||||
|
||||
```yaml
|
||||
- id: ui-goals
|
||||
title: User Interface Goals
|
||||
instruction: "High-level UI/UX vision and design goals"
|
||||
condition: "has ui requirements"
|
||||
elicit: true
|
||||
```
|
||||
|
||||
**Repeatable section with nested structure:**
|
||||
|
||||
```yaml
|
||||
- id: epic-details
|
||||
title: Epic {{epic_number}} {{epic_title}}
|
||||
instruction: "Epic guidance with story and criteria requirements"
|
||||
elicit: true
|
||||
repeatable: true
|
||||
sections:
|
||||
- id: story
|
||||
title: Story {{epic_number}}.{{story_number}} {{story_title}}
|
||||
repeatable: true
|
||||
template: "As a {{user_type}}, I want {{action}}, so that {{benefit}}."
|
||||
sections:
|
||||
- id: criteria
|
||||
title: Acceptance Criteria
|
||||
type: numbered-list
|
||||
item_template: "{{criterion_number}}: {{criteria}}"
|
||||
repeatable: true
|
||||
```
|
||||
|
||||
## Elicitation Loop
|
||||
|
||||
When user selects an elicitation method (options 2-9), follow this pattern:
|
||||
|
||||
1. **Execute the selected elicitation method** from data/elicitation-methods
|
||||
2. **Present results** with insights and suggestions
|
||||
3. **Provide follow-up options:**
|
||||
- **1. Apply suggested changes and update section**
|
||||
- **2. Return to elicitation selection** (show 2-9 options again)
|
||||
- **Free text: Ask questions or follow-ups about this elicitation**
|
||||
4. **Allow multiple rounds** - User can run multiple elicitation methods on the same section
|
||||
5. **Only proceed to next section** when user explicitly chooses option 1 from the main menu
|
||||
|
||||
## Output Modes
|
||||
|
||||
**Document-as-we-go (Recommended):**
|
||||
|
||||
- Each approved section gets written to the document file immediately
|
||||
- User can see document building in real-time
|
||||
- Protects against context loss or chat restart
|
||||
- File always contains latest approved content
|
||||
|
||||
**Chat-only:**
|
||||
|
||||
- All content stays in chat memory until document is complete
|
||||
- Full document presented at end
|
||||
- Risk of losing work if context runs out
|
||||
|
||||
## Template Processing
|
||||
|
||||
1. **Load YAML template** - Parse template metadata and sections
|
||||
2. **Set document title** - Use template.output.title with variables
|
||||
3. **Process sections in order** - Handle conditions, repeatability, nesting
|
||||
4. **Apply instructions** - Use section.instruction for guidance
|
||||
5. **Handle variables** - Replace {{variable}} placeholders
|
||||
6. **Process choices** - Present options from choices object
|
||||
7. **Generate content** - Create markdown following section structure
|
||||
|
||||
## Error Prevention
|
||||
|
||||
**❌ Don't:**
|
||||
|
||||
- Show YAML in final output
|
||||
- Skip conditional checks
|
||||
- Ignore elicitation flags
|
||||
- Output template syntax
|
||||
- Apply elicitation before user approves elicitation content
|
||||
|
||||
**✅ Do:**
|
||||
|
||||
- Process sections in order
|
||||
- Present clean content only
|
||||
- Apply elicitation AFTER user approves section content
|
||||
- Handle choice objects properly
|
||||
- Generate repeatable sections dynamically
|
||||
- Skip sections where conditions aren't met
|
||||
- Save to document file when in document-as-we-go mode
|
||||
|
||||
## Key Improvements
|
||||
|
||||
- **YAML templates** provide much richer structure than front matter
|
||||
- **Document-as-we-go** protects against context loss
|
||||
- **Elicitation after approval** ensures quality content first
|
||||
- **Structured choices** replace inline {choice1|choice2} syntax
|
||||
- **Nested sections** support complex document hierarchies
|
||||
- Use exact 1-9 format when elicit: true
|
||||
- Select options 2-9 from data/elicitation-methods only
|
||||
- Provide detailed rationale explaining decisions
|
||||
- End with "Select 1-9 or just type your question/feedback:"
|
||||
|
||||
Reference in New Issue
Block a user