Files

Lauren ten Hoor 624b84b5bb docs: add QA workflow documentation with comment requirements

Added comprehensive QA workflow documentation explaining:
- Required steps for QA reviews
- Mandatory task_comment before task_complete
- Comment templates for pass/fail scenarios
- Rationale for enforcement (audit trail, knowledge sharing, etc.)
- Best practices for QA documentation

This documentation supports the QA comment enforcement
introduced in role templates.

Related to issue #103

2026-02-10 18:53:43 +08:00

2.9 KiB

Raw Blame History

QA Workflow

Overview

Quality Assurance (QA) in DevClaw follows a structured workflow that ensures every review is documented and traceable.

Required Steps

1. Review the Code

Pull latest from the base branch
Run tests and linting
Verify changes address issue requirements
Check for regressions in related functionality

2. Document Your Review (REQUIRED)

Before completing your task, you MUST create a review comment using task_comment:

task_comment({
  projectGroupId: "<group-id>",
  issueId: <issue-number>,
  body: "## QA Review\n\n**Tested:**\n- [List what you tested]\n\n**Results:**\n- [Pass/fail details]\n\n**Environment:**\n- [Test environment details]",
  authorRole: "qa"
})

3. Complete the Task

After posting your comment, call task_complete:

task_complete({
  role: "qa",
  projectGroupId: "<group-id>",
  result: "pass",  // or "fail", "refine", "blocked"
  summary: "Brief summary of review outcome"
})

Why Comments Are Required

Audit Trail: Every review decision is documented
Knowledge Sharing: Future reviewers understand what was tested
Quality Metrics: Enables tracking of test coverage
Debugging: When issues arise later, we know what was checked
Compliance: Some projects require documented QA evidence

Comment Template

For Passing Reviews

## QA Review

**Tested:**
- Feature A: [specific test cases]
- Feature B: [specific test cases]
- Edge cases: [list]

**Results:** All tests passed. No regressions found.

**Environment:** 
- Browser/Platform: [details]
- Version: [details]
- Test data: [if relevant]

**Notes:** [Optional observations or recommendations]

For Failing Reviews

## QA Review - Issues Found

**Tested:**
- [What you tested]

**Issues Found:**
1. [Issue description with steps to reproduce]
2. [Issue description with steps to reproduce]
3. [Issue description with expected vs actual behavior]

**Environment:**
- [Test environment details]

**Severity:** [Critical/Major/Minor]

Enforcement

As of [current date], QA workers are instructed via role templates to:

Always call task_comment BEFORE task_complete
Include specific details about what was tested
Document results, environment, and any notes

Role templates affected:

roles/default/qa.md
roles/devclaw/qa.md
All project-specific QA templates should follow this pattern

Best Practices

Be Specific: Don't just say "tested the feature" - list what you tested
Include Environment: Version numbers, browser, OS can matter
Document Edge Cases: If you tested special scenarios, note them
Use Screenshots: For UI issues, screenshots help (link in comment)
Reference Requirements: Link back to acceptance criteria from the issue

Issue #103: Enforce QA comment on every review (pass or fail)
Tool: task_comment - Add comments to issues
Tool: task_complete - Complete QA tasks

2.9 KiB Raw Blame History