aios-core 2.1.6 → 2.2.1

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

@@ -1,425 +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
+# 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