aios-core 2.1.0

package/.aios-core/development/tasks/qa-backlog-add-followup.md

@@ -0,0 +1,425 @@
+# QA Task: Add Follow-up to Backlog
+
+**Agent:** @qa
+**Command:** `*backlog-add` (when used by @qa, defaults to type F)
+**Purpose:** Add follow-up item from QA review to backlog
+**Created:** 2025-01-16 (Story 6.1.2.6)
+
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: qaBacklogAddFollowup()
+responsável: Quinn (Guardian)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: target
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must exist
+
+- campo: criteria
+  tipo: array
+  origem: config
+  obrigatório: true
+  validação: Non-empty validation criteria
+
+- campo: strict
+  tipo: boolean
+  origem: User Input
+  obrigatório: false
+  validação: Default: true
+
+**Saída:**
+- campo: validation_result
+  tipo: boolean
+  destino: Return value
+  persistido: false
+
+- campo: errors
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: report
+  tipo: object
+  destino: File (.ai/*.json)
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Validation rules loaded; target available for validation
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check validation rules loaded; target available for validation
+    error_message: "Pre-condition failed: Validation rules loaded; target available for validation"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Validation executed; results accurate; report generated
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify validation executed; results accurate; report generated
+    error_message: "Post-condition failed: Validation executed; results accurate; report generated"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Validation rules applied; pass/fail accurate; actionable feedback
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert validation rules applied; pass/fail accurate; actionable feedback
+    error_message: "Acceptance criterion not met: Validation rules applied; pass/fail accurate; actionable feedback"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** validation-engine
+  - **Purpose:** Rule-based validation and reporting
+  - **Source:** .aios-core/utils/validation-engine.js
+
+- **Tool:** schema-validator
+  - **Purpose:** JSON/YAML schema validation
+  - **Source:** ajv or similar
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** run-validation.js
+  - **Purpose:** Execute validation rules and generate report
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/run-validation.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Validation Criteria Missing
+   - **Cause:** Required validation rules not defined
+   - **Resolution:** Ensure validation criteria loaded from config
+   - **Recovery:** Use default validation rules, log warning
+
+2. **Error:** Invalid Schema
+   - **Cause:** Target does not match expected schema
+   - **Resolution:** Update schema or fix target structure
+   - **Recovery:** Detailed validation error report
+
+3. **Error:** Dependency Missing
+   - **Cause:** Required dependency for validation not found
+   - **Resolution:** Install missing dependencies
+   - **Recovery:** Abort with clear dependency list
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-15 min (estimated)
+cost_estimated: $0.003-0.010
+token_usage: ~3,000-10,000 tokens
+```
+
+**Optimization Notes:**
+- Break into smaller workflows; implement checkpointing; use async processing where possible
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - quality-assurance
+  - testing
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Task Flow
+
+### 1. Elicit Follow-up Details
+```yaml
+elicit: true
+questions:
+  - Title (1-line description):
+    input: text
+    validation: min 10 chars, max 100 chars
+    example: "Add edge case tests for user authentication flow"
+
+  - Detailed Description:
+    input: textarea
+    validation: max 500 chars
+    placeholder: "Describe what needs to be followed up on and why"
+
+  - Priority:
+    options:
+      - Critical (🔴) - Blocking issue or security concern
+      - High (🟠) - Important but not blocking
+      - Medium (🟡) - Nice to have
+      - Low (🟢) - Optional improvement
+    default: Medium
+    note: "Critical/High follow-ups should be addressed before story completion"
+
+  - Related Story ID:
+    input: text
+    example: "6.1.2.6"
+    note: "Usually the story being reviewed"
+    required: true
+
+  - Tags (optional, comma-separated):
+    input: text
+    example: "testing, edge-case, security"
+    suggestions: ["testing", "edge-case", "security", "performance", "documentation"]
+
+  - Estimated Effort (optional):
+    input: text
+    example: "2 hours", "1 day"
+    default: "TBD"
+```
+
+### 2. Validate Related Story
+```javascript
+// QA review items MUST have a related story
+if (!relatedStory) {
+  throw new Error('QA follow-ups must be linked to a story. Use related story ID.');
+}
+
+// Validate story exists
+const storyPath = `docs/stories/**/*${relatedStory}*.md`;
+const matches = await glob(storyPath);
+
+if (matches.length === 0) {
+  throw new Error(`Story not found: ${relatedStory}`);
+}
+
+if (matches.length > 1) {
+  console.log('⚠️ Multiple stories matched, using first:');
+  matches.forEach(m => console.log(`  - ${m}`));
+}
+
+const storyFile = matches[0];
+```
+
+### 3. Add to Backlog
+```javascript
+const { BacklogManager } = require('.aios-core/scripts/backlog-manager');
+
+const manager = new BacklogManager('docs/stories/backlog.md');
+await manager.load();
+
+// QA always creates Follow-up type (F)
+const item = await manager.addItem({
+  type: 'F',  // Follow-up
+  title: title,
+  description: description,
+  priority: priority,
+  relatedStory: relatedStory,
+  createdBy: '@qa',
+  tags: tags,
+  estimatedEffort: estimatedEffort
+});
+
+console.log(`✅ Follow-up added to backlog: ${item.id}`);
+```
+
+### 4. Update Story QA Results (Optional)
+```yaml
+elicit: true
+question: "Add reference to QA Results section in story?"
+options:
+  - yes: Update story file with backlog reference
+  - no: Skip story update
+default: yes
+```
+
+```javascript
+if (updateStory) {
+  const storyContent = await fs.readFile(storyFile, 'utf8');
+
+  // Find QA Results section
+  const qaResultsMatch = storyContent.match(/## QA Results/);
+
+  if (qaResultsMatch) {
+    const updatedContent = storyContent.replace(
+      /## QA Results/,
+      `## QA Results\n\n**Follow-up Created:** [Backlog Item ${item.id}](../backlog.md) - ${title}\n`
+    );
+
+    await fs.writeFile(storyFile, updatedContent, 'utf8');
+    console.log(`✅ Story updated with backlog reference`);
+  } else {
+    console.log('⚠️ QA Results section not found in story, skipping update');
+  }
+}
+```
+
+### 5. Regenerate Backlog
+```javascript
+await manager.generateBacklogFile();
+
+console.log('✅ Backlog updated: docs/stories/backlog.md');
+```
+
+### 6. Summary Output
+```markdown
+## 📌 Follow-up Added to Backlog
+
+**ID:** ${item.id}
+**Type:** 📌 Follow-up (from QA review)
+**Title:** ${title}
+**Priority:** ${priorityEmoji} ${priority}
+**Related Story:** ${relatedStory}
+**Estimated Effort:** ${estimatedEffort}
+**Tags:** ${tags.join(', ') || 'None'}
+
+**Next Steps:**
+- Review in backlog: docs/stories/backlog.md
+- @po will prioritize with `*backlog-prioritize ${item.id}`
+- @dev will address before story completion (if Critical/High)
+
+${priority === 'Critical' || priority === 'High'
+  ? '⚠️ **HIGH PRIORITY** - Should be addressed before story completion'
+  : ''
+}
+```
+
+---
+
+## Example Usage
+
+```bash
+# During QA review of Story 6.1.2.6
+*backlog-add
+
+# Example responses:
+Title: Add integration tests for story index generator
+Description: Current implementation only has unit tests. Integration tests needed to verify end-to-end story scanning and index generation.
+Priority: High
+Related Story: 6.1.2.6
+Tags: testing, integration, coverage
+Effort: 3 hours
+Update story? yes
+
+# Output:
+✅ Follow-up added to backlog: 1763298742141
+✅ Story updated with backlog reference
+✅ Backlog updated: docs/stories/backlog.md
+```
+
+---
+
+## QA-Specific Rules
+
+1. **Type is always F (Follow-up)** - QA creates follow-ups, not tech debt
+2. **Related story is required** - All QA items linked to reviewed story
+3. **Priority guidance:**
+   - Critical: Security issue, data corruption risk, blocking bug
+   - High: Important test gap, significant edge case
+   - Medium: Nice-to-have test, minor gap
+   - Low: Optional improvement
+4. **Story update recommended** - Keep follow-ups visible in story file
+
+---
+
+## Error Handling
+
+- **No related story:** Require story ID, don't allow orphan follow-ups
+- **Story not found:** Show similar story names, allow retry
+- **QA Results section missing:** Log warning, skip story update
+- **Backlog locked:** Retry 3x with 1s delay
+
+---
+
+## Testing
+
+```bash
+# Test with sample story
+*backlog-add
+# Fill in test data
+# Verify:
+# - Item added to backlog with type=F
+# - createdBy = @qa
+# - Story file updated (if QA Results section exists)
+# - Priority reflected in backlog ordering
+```
+
+---
+
+**Related Tasks:**
+- `qa-review.md` - Comprehensive story review
+- `qa-gate.md` - Quality gate decision
+- `po-backlog-review.md` - PO reviews all follow-ups