--- name: ring:dev-validation description: | Development cycle validation gate (Gate 5) - validates all acceptance criteria are met and requires explicit user approval before completion. trigger: | - After review gate passes (Gate 4) - Implementation and tests complete - Need user sign-off on acceptance criteria NOT_skip_when: | - "Already validated" → Each iteration needs fresh validation. - "User will validate manually" → Gate 5 IS user validation. Cannot skip. sequence: after: [ring:requesting-code-review] related: complementary: [verification-before-completion] verification: automated: - command: "go test .\/... 2>&1 | grep -c PASS" description: "All tests pass" success_pattern: "[1-9][0-9]*" - command: "cat docs\/ring:dev-cycle\/current-cycle.json 2>\/dev\/null || cat docs\/ring:dev-refactor\/current-cycle.json | jq '.gates[4].verdict'" description: "Review gate passed" success_pattern: "PASS" manual: - "User has provided explicit APPROVED or REJECTED decision" - "All acceptance criteria have verified evidence" - "Validation checklist presented to user" examples: - name: "Successful validation" context: "4 acceptance criteria, all tests pass" expected_flow: | 1. Gather evidence for each criterion 2. Build validation checklist with evidence types 3. Present to user with APPROVED\/REJECTED options 4. User selects APPROVED 5. Document approval, proceed to feedback loop - name: "Validation rejection" context: "AC-3 not met (response time too slow)" expected_flow: | 1. Present validation checklist 2. User identifies AC-3 failure 3. User selects REJECTED with reason 4. Create remediation task 5. Return to Gate 0 for fixes --- # Dev Validation (Gate 5) ## Overview Final validation gate requiring explicit user approval. Present evidence that each acceptance criterion is met and obtain APPROVED or REJECTED decision. **Core principle:** Passing tests and code review DO NOT guarantee requirements are met. User validation confirms implementation matches intent. ## Pressure Resistance See [shared-patterns\/shared-pressure-resistance.md](..\/shared-patterns\/shared-pressure-resistance.md) for universal pressure scenarios. **Gate 5-specific note:** User MUST respond with "APPROVED" or "REJECTED: [reason]". No other responses accepted. Silence ≠ approval. ## Self-Approval Prohibition - Same agent approving code it implemented - Role switching to self-approve (e.g., ring:backend-engineer → ring:code-reviewer) - Interpreting silence as approval - Proceeding without explicit APPROVED\/REJECTED <\/forbidden> **HARD GATE:** The agent that implemented code CANNOT approve validation for that same code. | Scenario | Allowed? | Action | |----------|----------|--------| | Different agent\/human approves | YES | Proceed with approval | | Same agent self-approves | no | STOP - requires external approval | | User explicitly approves | YES | User approval always valid | **If you implemented the code, you CANNOT approve it. Wait for user or different reviewer.** **Important:** "Different agent" means different human\/entity. The same human using different agent roles (ring:backend-engineer-* → ring:code-reviewer) is STILL self-approval and PROHIBITED. See [CLAUDE.md](https:\/\/raw.githubusercontent.com\/LerianStudio\/ring\/main\/CLAUDE.md) for the canonical validation policy. --- ## Severity Calibration **When presenting validation results to user, issues are categorized by severity:** | Severity | Criteria | Examples | Action Required | |----------|----------|----------|-----------------| | **CRITICAL** | Acceptance criterion completely unmet | AC-1: "User can login" but login doesn't work at all | MUST fix before approval. Return to Gate 0. | | **HIGH** | Acceptance criterion partially met or degraded | AC-2: "Response < 200ms" but actually 800ms | MUST fix before approval. Return to Gate 0. | | **MEDIUM** | Edge case or non-critical requirement gap | AC-3 met for happy path, fails for empty input | SHOULD fix before approval. User decides. | | **LOW** | Quality issue, requirement technically met | Code works but is hard to understand\/maintain | MAY fix or document. User decides. | **Severity Assignment Rules:** - Unmet acceptance criterion = CRITICAL (requirement not satisfied) - Degraded performance\/quality vs criterion = HIGH (requirement barely met) - Edge case failures = MEDIUM (main path works, edges don't) - Quality\/maintainability with working code = LOW (works but suboptimal) **Why This Matters:** - User needs to understand impact severity when deciding APPROVED vs REJECTED - CRITICAL\/HIGH = automatic REJECTED recommendation - MEDIUM\/LOW = user judgment call with context **Example Validation Checklist with Severity:** ```markdown ## Validation Results | AC # | Criterion | Evidence | Status | Severity | |------|-----------|----------|--------|----------| | AC-1 | User can login | ✅ Tests pass, manual verification | MET | - | | AC-2 | Response < 200ms | ⚠️ Measured 350ms average | not MET | HIGH | | AC-3 | Input validation | ⚠️ Works for valid input, crashes on empty | PARTIAL | MEDIUM | | AC-4 | Error messages clear | ✅ All errors have user-friendly messages | MET | - | **Overall Validation:** REJECTED (1 HIGH issue: AC-2 response time) **Recommendation:** Fix AC-2 (HIGH) before approval. AC-3 (MEDIUM) user can decide. ``` --- ## Common Rationalizations - REJECTED See [shared-patterns\/shared-anti-rationalization.md](..\/shared-patterns\/shared-anti-rationalization.md) for universal anti-rationalizations (including Validation section). **Gate 5-specific rationalizations:** | Excuse | Reality | |--------|---------| | "Async over sync - work in parallel" | Validation is a GATE, not async task. STOP means STOP. | | "Continue other tasks while waiting" | Other tasks may conflict. Validation blocks all related work. | | "User delegated approval to X" | Delegation ≠ stakeholder approval. Only original requester can approve. | | "I implemented it, I know requirements" | Knowledge ≠ approval authority. Implementer CANNOT self-approve. | | "I'll switch to QA role to approve" | Role switching is STILL self-approval. PROHIBITED. | ## Red Flags - STOP See [shared-patterns\/shared-red-flags.md](..\/shared-patterns\/shared-red-flags.md) for universal red flags (including Validation section). If you catch yourself thinking any of those patterns, STOP immediately. Wait for explicit "APPROVED" or "REJECTED". --- ## Ambiguous Response Handling - Response is "Looks good", "Sure", "Ok", "Fine" - Response is emoji only (👍, ✅) - Response is "Go ahead", "Ship it" - Response contains conditional ("APPROVED if X", "APPROVED with caveats") <\/block_condition> If any condition matches, ask for explicit APPROVED or REJECTED. **User responses that are not valid approvals:** | Response | Status | Action Required | |----------|--------|-----------------| | "Looks good" | ❌ AMBIGUOUS | "To confirm, please respond with APPROVED or REJECTED: [reason]" | | "Sure" \/ "Ok" \/ "Fine" | ❌ AMBIGUOUS | Ask for explicit APPROVED | | "👍" \/ "✅" | ❌ AMBIGUOUS | Emojis are not formal approval. Ask for APPROVED. | | "Go ahead" | ❌ AMBIGUOUS | Ask for explicit APPROVED | | "Ship it" | ❌ AMBIGUOUS | Ask for explicit APPROVED | | "APPROVED" | ✅ VALID | Proceed to next gate | | "REJECTED: [reason]" | ✅ VALID | Document reason, return to Gate 0 | | "APPROVED if X" | ❌ CONDITIONAL | Not approved until X is verified. Status = PENDING. | | "APPROVED with caveats" | ❌ CONDITIONAL | Not approved. List caveats, verify each, then re-ask. | | "APPROVED but fix Y later" | ❌ CONDITIONAL | Not approved. Y must be addressed first. | **When user gives ambiguous response:** ``` "Thank you for the feedback. For formal validation, please confirm with: - APPROVED - to proceed with completion - REJECTED: [reason] - to return for fixes Which is your decision?" ``` **Never interpret intent. Require explicit keyword.** --- ## Awaiting Approval - STOP all WORK - STOP all work when validation request is presented - Wait for explicit APPROVED or REJECTED - Do not proceed with any "quick fixes" while waiting <\/cannot_skip> **When validation request is presented:** 1. **STOP all WORK** on this feature, module, and related code 2. **DO not** proceed to documentation, refactoring, or "quick fixes" 3. **DO not** work on "unrelated" tasks in the same codebase 4. **WAIT** for explicit user response **User unavailability is not permission to:** - Assume approval - Work on "low-risk" next steps - Redefine criteria as "already met" - Proceed with "we'll fix issues later" **Document pending status and WAIT.** ## Approval Format - MANDATORY Valid responses: - "APPROVED" → Proceed to next gate - "REJECTED: [reason]" → Return for fixes <\/user_decision> **User MUST respond with exactly one of:** ✅ **"APPROVED"** - All criteria verified, proceed to next gate ✅ **"REJECTED: [specific reason]"** - Issues found, fix and revalidate **not acceptable:** - ❌ "Looks good" (vague) - ❌ "👍" (ambiguous) - ❌ Silence (not a response) - ❌ "Approved with minor issues" (partial = REJECTED) **If user provides ambiguous response, ask for explicit APPROVED or REJECTED.** --- ## Prerequisites Before starting this gate: - All tests pass (Gate 3 verified) - Code review passed (Gate 4 VERDICT: PASS) - Implementation is complete and stable ## Steps 1-4: Evidence Collection and Validation | Step | Action | Output | |------|--------|--------| | **1. Gather Evidence** | Collect proof per criterion | Table: Criterion, Evidence Type (Test\/Demo\/Log\/Manual\/Metric), Location, Status | | **2. Verify** | Execute verification (automated: `npm test --grep "AC-X"`, manual: documented steps with Result + Screenshot) | VERIFIED\/FAILED per criterion | | **3. Build Checklist** | For each AC: Status + Evidence list + Verification method | Validation Checklist | | **4. Present Request** | Task Summary + Validation Table + Test Results + Review Summary + Artifacts | USER DECISION block with APPROVED\/REJECTED options | **Validation Request format:** ``` VALIDATION REQUEST - [TASK-ID] Task: [title], [description], [date] Criteria: Table (Criterion | Status | Evidence) Tests: Total\/Passed\/Failed\/Coverage Review: VERDICT + issue counts Artifacts: Code, Tests, Docs links USER DECISION REQUIRED: [ ] APPROVED - proceed [ ] REJECTED - specify: which criterion, what's missing, what's wrong ``` ## Steps 5-6: Handle Decision and Document | Decision | Actions | Documentation | |----------|---------|---------------| | **APPROVED** | 1. Document (Task, Approver, Date, Notes) → 2. Update status → 3. Proceed to feedback loop | Validation Approved record | | **REJECTED** | 1. Document (Task, Rejector, Date, Criterion failed, Issue, Expected vs Actual) → 2. Create remediation task → 3. Return to Gate 0 → 4. After fix: restart from Gate 3 → 5. Track in feedback loop | Validation Rejected + Remediation Required records | **Validation Record format:** Date, Validator, Decision, Criteria Summary (X\/Y), Evidence Summary (tests\/manual\/perf), Decision Details, Next Steps ## Validation Best Practices | Category | Strong Evidence | Weak Evidence (avoid) | |----------|-----------------|----------------------| | **Evidence Quality** | Automated test + assertion, Screenshot\/recording, Log with exact values, Metrics within threshold | "Works on my machine", "Tested manually" (no details), "Should be fine", Indirect evidence | | **Verifiable Criteria** | "User can login" → test login + verify session | "System is fast" → needs specific metric | | | "Page loads <2s" → measure + show metric | "UX is good" → needs measurable criteria | ## Handling Partial Validation If some criteria pass but others fail: 1. **Do not partially approve** 2. Mark entire validation as REJECTED 3. Document which criteria passed (won't need re-verification) 4. Document which criteria failed (need fixes) 5. After fixes, re-verify only failed criteria 6. Present updated checklist for approval ## Anti-Patterns **Never:** - Skip validation because "tests pass" - Auto-approve without user decision - Assume criterion is met without evidence - Accept vague approval ("looks good") - Proceed while awaiting decision - Reuse old evidence for new changes **Always:** - Present evidence for every criterion - Require explicit APPROVED\/REJECTED decision - Document rejection reason in detail - Track validation metrics - Re-verify after any changes ## Execution Report Base metrics per [shared-patterns\/output-execution-report.md](..\/shared-patterns\/output-execution-report.md). | Metric | Value | |--------|-------| | Duration | Xm Ys | | Criteria Validated | X\/Y | | Evidence Collected | X automated, Y manual | | User Decision | APPROVED\/REJECTED | | Rejection Reason | [if applicable] | | Result | Gate passed \/ Returned to Gate 0 | ## Edge Cases | Scenario | Action | |----------|--------| | **User Unavailable** | Document pending → Do not proceed → Set escalation → Block task completion | | **Criterion Ambiguity** | STOP → Ask user to clarify → Update AC → Re-verify with new understanding | | **New Requirements** | Document as new req → Complete current validation on original AC → Create new task → no scope creep |