ace-task 0.31.0

data/handbook/workflow-instructions/task/review-questions.wf.md

@@ -0,0 +1,411 @@
+---
+doc-type: workflow
+purpose: Resolve clarifying questions for tasks and implementation readiness
+ace-docs:
+  last-updated: '2026-03-21'
+---
+
+# Review Questions Workflow Instruction
+
+## Goal
+
+Interactively review and resolve questions in tasks marked with `needs_review: true`, capturing answers and updating task definitions to make them implementation-ready without requiring further clarification.
+
+## Prerequisites
+
+- One or more tasks exist with `needs_review: true` flag
+- Understanding of task review question format and structure
+- Authority to make implementation decisions or access to stakeholders
+- Write access to task files in `.ace-tasks/`
+- Access to `ace-task list` tool for finding tasks
+
+## Project Context Loading
+
+- Read and follow: `ace-bundle wfi://bundle`
+- Load existing review workflow: `ace-bundle wfi://task/review`
+
+## Process Steps
+
+1. **Find Next Task Needing Review:**
+
+   ```bash
+   # List tasks by status (needs_review is a metadata field, not a filter)
+   ace-task list --status draft
+   ace-task list --status pending
+
+   # You'll need to check task files manually for needs_review: true flag
+   # Or use ace-search to find tasks with the flag:
+   cd .ace-tasks && ace-search "needs_review: true" --content
+   ```
+
+   **Selection Strategy:**
+   - Prioritize HIGH priority tasks first
+   - Within same priority, select oldest tasks
+   - Consider task dependencies (review prerequisites first)
+   - Note the task path for loading
+   - **Note**: `needs_review` is a task metadata field that must be checked by reading task files
+
+2. **Load and Analyze Task Questions:**
+   
+   - **Read Task File:**
+     ```bash
+     # Read the selected task
+     cat [task-path]
+     ```
+   
+   - **Identify Question Structure:**
+     - Locate `## Review Questions (Pending Human Input)` section
+     - Note question priorities: [HIGH], [MEDIUM], [LOW]
+     - Review research context for each question
+     - Understand suggested defaults and rationale
+   
+   - **Prepare Question Presentation:**
+     - Group questions by priority level
+     - Order within groups by dependency/logic flow
+     - Prepare to present context with each question
+
+3. **Interactive Question Review Process:**
+   
+   ### For Each Question (Priority Order):
+   
+   **a. Present Question with Full Context:**
+   ```markdown
+   ========================================
+   QUESTION [1/N] - [PRIORITY LEVEL]
+   ========================================
+   
+   **Question**: [Question text]
+   
+   **Research Conducted**: 
+   [Research findings from task]
+   
+   **Current Context**:
+   [Relevant project/technical context]
+   
+   **Suggested Default**:
+   [Default recommendation with rationale]
+   
+   **Why Human Input Needed**:
+   [Business/design decision reasoning]
+   
+   **Potential Options**:
+   1. [Option A with implications]
+   2. [Option B with implications]
+   3. [Option C with implications]
+   4. [Custom answer]
+   
+   Please provide your decision:
+   ```
+   
+   **b. Capture User Answer:**
+   - Record the exact answer provided
+   - Ask for optional rationale if not clear
+   - Confirm understanding before proceeding
+   - Note any follow-up implications
+   
+   **c. Document Answer Format:**
+   ```markdown
+   ### [RESOLVED] Original Question Title
+   - **Decision**: [User's answer]
+   - **Rationale**: [Why this choice was made]
+   - **Implications**: [What this means for implementation]
+   - **Resolved by**: [User/Role]
+   - **Date**: [YYYY-MM-DD]
+   ```
+
+4. **Save Answers Progressively:**
+   
+   **After Each Answer:**
+   - Update the task file immediately
+   - Move question from pending to resolved section
+   - Preserve original question for audit trail
+   - Add resolution details
+   
+   **Answer Integration Pattern:**
+   ```markdown
+   ## Review Questions (Resolved)
+   
+   ### ✅ [RESOLVED] How should we handle session timeouts?
+   - **Original Priority**: HIGH
+   - **Decision**: Implement 12-hour sessions with 2-hour idle timeout
+   - **Rationale**: Balances security with user convenience per OWASP
+   - **Implementation Notes**: 
+     - Use refresh tokens for extension
+     - Log timeout events for monitoring
+   - **Resolved by**: Product Owner
+   - **Date**: 2025-01-30
+   
+   ## Review Questions (Pending Human Input)
+   
+   ### [MEDIUM] Remaining Question
+   - [ ] [Question still needing answer...]
+   ```
+
+5. **Update Task Definition with Answers:**
+   
+   **Integration Points by Task Section:**
+   
+   ### Technical Specifications:
+   - Add concrete configuration values from answers
+   - Update implementation approach based on decisions
+   - Specify exact thresholds, limits, quotas
+   
+   ### Implementation Notes:
+   - Document specific technical choices made
+   - Add configuration examples with resolved values
+   - Include edge case handling per decisions
+   
+   ### Success Criteria:
+   - Update measurable targets with specific values
+   - Add validation criteria from answers
+   - Include performance thresholds decided
+   
+   ### Configuration Files:
+   - Update code examples with actual values
+   - Replace placeholders with decisions
+   - Add comments explaining choices
+   
+   **Example Integration:**
+   ```javascript
+   // Before (with question)
+   numberOfRuns: 3, // TODO: How many runs for reliability?
+   
+   // After (with answer integrated)
+   numberOfRuns: 3, // Confirmed: 3 runs for median reliability (decided 2025-01-30)
+   ```
+
+6. **Complete Review Session:**
+   
+   **When All Questions Answered:**
+   - Remove `needs_review: true` flag from metadata
+   - Move all questions to Resolved section
+   - Add review completion note
+   
+   **Completion Metadata Update:**
+   ```yaml
+   ---
+   id: v.0.2.0+task.123
+   status: draft  # Or current status
+   priority: high
+   estimate: 4-6h  # Update if needed based on decisions
+   dependencies: none
+   # needs_review: true  # REMOVED
+   review_completed: 2025-01-30
+   reviewed_by: [User/Role]
+   ---
+   ```
+   
+   **Add Implementation Readiness Note:**
+   ```markdown
+   ## Review Completion Summary
+   
+   **Date**: 2025-01-30
+   **Reviewed by**: [User/Role]
+   **Questions Resolved**: 5 (3 HIGH, 2 MEDIUM)
+   **Implementation Readiness**: ✅ Ready for implementation
+   
+   **Key Decisions Made**:
+   - Lighthouse CI will run on all builds with sampling
+   - Performance thresholds: 5-point warning, 10-point failure
+   - Mobile-first testing with 3 runs for reliability
+   - 50ms monitoring overhead budget approved
+   - BigQuery integration deferred to Phase 2
+   ```
+
+7. **Handle Partial Reviews:**
+   
+   **If Review Must Be Interrupted:**
+   - Save all answered questions immediately
+   - Keep `needs_review: true` flag
+   - Add progress note with timestamp
+   - Document which questions remain
+   
+   **Progress Note Format:**
+   ```markdown
+   ## Review Progress Notes
+   
+   ### Session: 2025-01-30 14:30
+   - Resolved: 3 of 5 questions
+   - Remaining: 2 MEDIUM priority questions
+   - Blocked on: Need input from DevOps team
+   - Next steps: Schedule follow-up for remaining items
+   ```
+
+8. **Batch Review Mode (Optional):**
+   
+   **For Multiple Tasks:**
+   ```bash
+   # Generate review queue (find tasks with needs_review flag)
+   cd .ace-tasks && ace-search "needs_review: true" --content --files-with-matches > ../review-queue.txt
+
+   # Process each task systematically
+   for task in $(cat review-queue.txt); do
+     echo "Reviewing: $task"
+     # Follow steps 2-6 for each task
+   done
+   ```
+   
+   **Batch Summary Report:**
+   ```markdown
+   ## Batch Review Summary - 2025-01-30
+   
+   **Tasks Reviewed**: 3
+   **Questions Resolved**: 12 total
+   - Task.123: 5 questions ✅
+   - Task.124: 4 questions ✅  
+   - Task.125: 3 questions (2 resolved, 1 pending)
+   
+   **Common Decisions**:
+   - All performance monitoring at 25% sampling
+   - Consistent 5/10 point threshold strategy
+   - Mobile-first testing approach approved
+   ```
+
+## Success Criteria
+
+- All HIGH priority questions answered with clear decisions
+- Answers documented with rationale and implications
+- Task definition updated with concrete implementation details
+- Configuration examples include actual decided values
+- `needs_review` flag removed when fully resolved
+- Task achieves "implementation-ready" state
+- No ambiguity remains that would block implementation
+- Review completion summary added to task
+
+## Common Question Types and Answer Templates
+
+### Performance/Threshold Questions
+```markdown
+**Question**: What performance degradation threshold should trigger build failure?
+**Answer Template**:
+- Warning threshold: [X points/percent]
+- Failure threshold: [Y points/percent]
+- Applies to: [specific metrics]
+- Exception handling: [if any]
+```
+
+### Configuration/Setup Questions
+```markdown
+**Question**: Should this run in CI/CD or local only?
+**Answer Template**:
+- Environments: [local, CI, production]
+- Trigger conditions: [PR, merge, manual]
+- Resource limits: [if applicable]
+- Cost considerations: [if applicable]
+```
+
+### Feature Scope Questions
+```markdown
+**Question**: Should we include [feature X] in this implementation?
+**Answer Template**:
+- Include in current scope: [Yes/No]
+- If deferred, target step: [Step N]
+- Dependencies affected: [list]
+- Alternative approach: [if not included]
+```
+
+### Technical Approach Questions
+```markdown
+**Question**: Which library/tool should we use for [purpose]?
+**Answer Template**:
+- Selected option: [Library/Tool name]
+- Version constraint: [if specific]
+- Rationale: [why chosen]
+- Fallback option: [if first choice fails]
+```
+
+## Integration with Task Workflows
+
+### Before review-questions:
+- `review-task`: Generates questions needing answers
+- `draft-task`: Creates tasks that may need clarification
+
+### After review-questions:
+- `plan-task`: Can proceed with clear requirements
+- `work-on-task`: Implementation without ambiguity
+- Task is ready for execution without blockers
+
+### Parallel workflows:
+- `create-adr`: Document significant technical decisions
+- `create-test-cases`: Define tests based on decisions
+
+## Error Handling
+
+### Common Issues:
+
+**"No tasks need review"**
+- Run `ace-task list needs-review` (preset) or `cd .ace-tasks && ace-search "needs_review: true" --content`
+- Check if reviews were already completed
+- Look for tasks with questions but missing flag
+
+**"Cannot parse question format"**
+- Ensure questions follow standard format
+- Check for `## Review Questions` section
+- Verify markdown structure is valid
+
+**"Conflicting answers"**
+- Review previous decisions for consistency
+- Document why this case differs
+- Consider creating ADR for significant changes
+
+## Usage Examples
+
+### Example 1: Single Task Review
+```
+User: "Review questions for the Lighthouse CI task"
+
+Process:
+1. Load task.123 with 5 pending questions
+2. Present each question with context:
+   Q1 [HIGH]: "Should Lighthouse CI run on all builds?"
+   - Show research about build times
+   - Present cost implications
+   - Suggest: "PR checks + production"
+3. Capture answer: "Yes, but with different configs"
+4. Document decision with rationale
+5. Update task config examples with decision
+6. Continue through all 5 questions
+7. Remove needs_review flag
+8. Add completion summary
+Result: Task ready for implementation
+```
+
+### Example 2: Batch Review Session
+```
+User: "Review all pending task questions"
+
+Process:
+1. Find 3 tasks needing review (123, 124, 125)
+2. Start with highest priority (task.123)
+3. Work through all questions systematically
+4. Save progress after each task
+5. Generate batch summary report
+6. Flag any that need follow-up
+Result: 2 tasks ready, 1 needs additional input
+```
+
+### Example 3: Partial Review with Handoff
+```
+User: "Review what I can answer for task.124"
+
+Process:
+1. Load 4 questions from task.124
+2. Answer technical questions (2 resolved)
+3. Flag business questions for Product Owner
+4. Save partial progress with notes
+5. Keep needs_review flag active
+6. Document what remains and who should answer
+Result: Partial resolution with clear next steps
+```
+
+## Key Value: Structured Decision Capture
+
+This workflow ensures:
+1. **No Lost Context**: All research and reasoning preserved
+2. **Audit Trail**: Clear record of who decided what and why
+3. **Implementation Clarity**: Developers have exact values and approaches
+4. **Efficient Reviews**: Questions presented with full context for quick decisions
+5. **Progressive Resolution**: Can handle partial reviews and handoffs
+6. **Batch Processing**: Efficiently review multiple tasks in one session
+
+The workflow transforms tasks from "blocked on questions" to "ready to build" through systematic, documented decision-making.

data/handbook/workflow-instructions/task/review-work.wf.md

@@ -0,0 +1,146 @@
+---
+doc-type: workflow
+purpose: Review implementation work before completion
+ace-docs:
+  last-updated: '2026-03-21'
+---
+
+# Review Work Workflow Instruction
+
+## Goal
+
+Critically evaluate work execution output for completeness, credibility, and delivery readiness. This workflow acts as the adversarial quality gate between execution and delivery. Work that passes this review should be complete enough to serve as a PR description or implementation report.
+
+## When to Use
+
+- As Phase 2 (self-critique) in a work execution step
+- After any implementation report is produced, before declaring work complete
+- When reviewing execution quality in ace-assign pipeline steps
+
+## Evaluation Dimensions
+
+Evaluate the work output against these six dimensions. Score each as **PASS**, **WEAK**, or **FAIL**.
+
+### 1. Plan Adherence
+
+Every item from the implementation plan must be addressed in the execution output. No silent drops.
+
+**PASS:** Every plan item has a corresponding execution result — completed, modified with rationale, or explicitly deferred.
+**WEAK:** Most plan items addressed but 1-2 minor items not mentioned.
+**FAIL:** Plan items silently dropped with no explanation.
+
+**Check for:**
+- Plan items with no corresponding execution mention
+- Scope changes without documented rationale
+- New work introduced that wasn't in the plan (scope creep)
+- Deferred items without justification
+
+### 2. Change Credibility
+
+Every claimed change must reference specific file paths, use valid code patterns, and match the project's actual structure.
+
+**PASS:** All changes reference real file paths, use correct syntax, and match project conventions.
+**WEAK:** Most changes are specific but some lack file paths or use approximate descriptions.
+**FAIL:** Vague claims like "updated the module" or references to non-existent patterns.
+
+**Check for:**
+- Changes described without file paths
+- Code snippets that don't match the project's language or framework conventions
+- References to files or modules that don't exist in the project
+- Descriptions too vague to verify ("improved error handling")
+
+### 3. Test Coverage Verification
+
+Tests must include concrete assertions and cover edge cases, not just happy paths.
+
+**PASS:** Test scenarios named with specific inputs, expected outputs, and edge case coverage.
+**WEAK:** Tests cover happy paths but edge cases are thin or unspecified.
+**FAIL:** Generic "tests added" claims or no test evidence for code changes.
+
+**Check for:**
+- "Tests pass" without listing what was tested
+- Missing edge case coverage for boundary conditions
+- No error path testing
+- Test file paths not specified
+
+### 4. Convention Compliance
+
+Naming, style, error messages, and patterns must match established project conventions.
+
+**PASS:** All changes follow project naming patterns, code style, and error message conventions.
+**WEAK:** Minor deviations that don't affect functionality.
+**FAIL:** Systematic convention violations or introduction of inconsistent patterns.
+
+**Check for:**
+- Naming that breaks established conventions (snake_case vs camelCase, prefixes, etc.)
+- Error messages that don't follow project patterns
+- File placement that violates project structure
+- New patterns introduced without justification when existing patterns apply
+
+### 5. Risk Mitigation Evidence
+
+Risks identified in the plan must have corresponding mitigation actions in the execution.
+
+**PASS:** Each identified risk has a documented mitigation action or resolution.
+**WEAK:** Most risks addressed but some mitigations are implicit rather than explicit.
+**FAIL:** Risks from the plan ignored in execution, or new risks introduced without mitigation.
+
+**Check for:**
+- Plan risks with no corresponding mitigation evidence
+- New risks introduced during execution without acknowledgment
+- Cross-package impacts not verified
+- Breaking changes without backward compatibility consideration
+
+### 6. Delivery Readiness
+
+The execution output must be complete enough that a reviewer can assess the full scope of changes.
+
+**PASS:** Output includes complete change manifest, test results, and remaining work (if any) clearly documented.
+**WEAK:** Output covers main changes but missing minor details a reviewer would need.
+**FAIL:** Output is incomplete — missing change descriptions, no test evidence, or unclear what was actually done.
+
+**Check for:**
+- Missing summary of what changed and why
+- No test execution evidence
+- Unclear boundary between completed and remaining work
+- Missing information a PR reviewer would need
+
+## Output Format
+
+Produce the critique in this structure:
+
+```markdown
+## Work Critique
+
+**Verdict:** SHIP IT | NEEDS REVISION | INCOMPLETE
+
+### Dimension Scores
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Plan Adherence | PASS/WEAK/FAIL | One-line finding |
+| Change Credibility | PASS/WEAK/FAIL | One-line finding |
+| Test Coverage Verification | PASS/WEAK/FAIL | One-line finding |
+| Convention Compliance | PASS/WEAK/FAIL | One-line finding |
+| Risk Mitigation Evidence | PASS/WEAK/FAIL | One-line finding |
+| Delivery Readiness | PASS/WEAK/FAIL | One-line finding |
+
+### Critical Findings
+- [List specific issues that MUST be fixed before delivery]
+
+### Strengths
+- [List what the execution does well]
+```
+
+## Verdict Criteria
+
+- **SHIP IT:** No FAIL scores, at most one WEAK score
+- **NEEDS REVISION:** No more than two FAIL scores, or three+ WEAK scores
+- **INCOMPLETE:** Three or more FAIL scores
+
+## Review Principles
+
+- Be adversarial. Your job is to find gaps between the plan and the execution, not to validate effort.
+- Compare the plan and execution item-by-item. Every plan item needs a resolution.
+- Demand specificity. "Updated the code" is not evidence of a change.
+- A shipped report is a commitment. Ensure every claim is verifiable.