Session QA Eligibility

Check investigation session QA skip eligibility per ADR-034.

Triggers

Check if I can skip QA
Am I eligible for investigation-only?
Verify investigation session eligibility

Process

User Request: Check QA eligibility
    |
    v
+---------------------------------------------+
| Phase 1: GET STAGED FILES                   |
| - Run git diff --cached --name-only        |
| - Collect all staged file paths            |
+---------------------------------------------+
    |
    v
+---------------------------------------------+
| Phase 2: CHECK ALLOWLIST                    |
| - Compare against allowed paths:           |
|   * .agents/sessions/                      |
|   * .agents/analysis/                      |
|   * .agents/retrospective/                 |
|   * .serena/memories/                      |
|   * .agents/security/                      |
| - Identify violations                      |
+---------------------------------------------+
    |
    v
+---------------------------------------------+
| Phase 3: RETURN RESULT                      |
| - Eligible: true if all files in allowlist |
| - Eligible: false if any violations        |
| - Include violations list for debugging    |
+---------------------------------------------+

Quick Reference

| Skill | Purpose | When to Use | |-------|---------|-------------| | Test-InvestigationEligibility | Check if staged files qualify for investigation-only QA skip | Before committing with SKIPPED: investigation-only |

Test Investigation Eligibility

Check if staged files qualify for investigation-only QA skip per ADR-034.

Usage

pwsh .claude/skills/session-qa-eligibility/scripts/Test-InvestigationEligibility.ps1

Output

Returns JSON with:

| Field | Type | Description | |-------|------|-------------| | Eligible | boolean | true if all staged files are in allowlist | | StagedFiles | array | All staged file paths | | Violations | array | Files not in allowlist (empty if eligible) | | AllowedPaths | array | Reference list of allowed path prefixes | | Error | string | Present only on git errors |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success (eligibility result in JSON output) |

Note: The script always exits 0. Check the Eligible field in the JSON output to determine eligibility. The Error field is present when git commands fail.

Error Handling

| Scenario | Behavior | Output | |----------|----------|--------| | Not in git repository | Returns JSON with Eligible: false | Error field explains the issue | | Git command fails | Returns JSON with Eligible: false | Error field explains the issue | | Empty staged files | Returns JSON with Eligible: true | StagedFiles is empty array | | Mixed allowed/disallowed files | Returns JSON with Eligible: false | Violations lists disallowed files |

Example Outputs

Eligible (investigation-only files):

{
  "Eligible": true,
  "StagedFiles": [".agents/sessions/.agents/sessions/2025-01-01-session-01.json"],
  "Violations": [],
  "AllowedPaths": [
    ".agents/sessions/",
    ".agents/analysis/",
    ".agents/retrospective/",
    ".serena/memories/",
    ".agents/security/"
  ]
}

Not eligible (contains code files):

{
  "Eligible": false,
  "StagedFiles": [
    ".agents/sessions/.agents/sessions/2025-01-01-session-01.json",
    "scripts/MyScript.ps1"
  ],
  "Violations": ["scripts/MyScript.ps1"],
  "AllowedPaths": [
    ".agents/sessions/",
    ".agents/analysis/",
    ".agents/retrospective/",
    ".serena/memories/",
    ".agents/security/"
  ]
}

Git error:

{
  "Eligible": false,
  "StagedFiles": [],
  "Violations": [],
  "AllowedPaths": [
    ".agents/sessions/",
    ".agents/analysis/",
    ".agents/retrospective/",
    ".serena/memories/",
    ".agents/security/"
  ],
  "Error": "Not in a git repository or git command failed"
}

Agent Workflow Integration

SESSION-PROTOCOL.md Relationship

This skill implements the verification step for Phase 2.5: QA Validation of the Session End Protocol:

SESSION-PROTOCOL.md (Phase 2.5: QA Validation)
                │
                ├── Feature implementation → MUST invoke qa agent
                │
                └── Investigation session → MAY skip QA
                        │
                        └── Test-InvestigationEligibility.ps1
                                │
                                ├── Eligible: true → Use "SKIPPED: investigation-only"
                                │
                                └── Eligible: false → MUST invoke qa agent

Workflow: Before Committing Investigation Work

1. Stage your files
   │
   └── git add .agents/sessions/... .serena/memories/...

2. Run eligibility check
   │
   └── pwsh .claude/skills/session-qa-eligibility/scripts/Test-InvestigationEligibility.ps1

3. Check output
   │
   ├── Eligible: true
   │   └── Safe to commit with "SKIPPED: investigation-only"
   │
   └── Eligible: false
       │
       ├── Check Violations array
       │   └── Either: Remove violating files from staging
       │   └── Or: Start new session for implementation work
       │
       └── Invoke qa agent for the implementation work

Integration with Session End Checklist

Use this skill to validate the QA skip condition:

### Session End (COMPLETE ALL before closing)

| Req | Step | Status | Evidence |
|-----|------|--------|----------|
| MUST | Route to qa agent (feature implementation) | [x] | `SKIPPED: investigation-only` - Verified via Test-InvestigationEligibility.ps1 |

Allowed Paths (Investigation Allowlist)

These paths qualify for investigation-only QA exemption:

| Path | Purpose | |------|---------| | .agents/sessions/ | Session logs documenting work | | .agents/analysis/ | Investigation outputs and findings | | .agents/retrospective/ | Learnings and retrospective documents | | .serena/memories/ | Cross-session context storage | | .agents/security/ | Security assessments and reviews |

Important: This allowlist MUST match exactly with scripts/Validate-SessionJson.ps1 $InvestigationAllowlist. The patterns are validated by Pester tests to ensure consistency.

Anti-Patterns

| Avoid | Why | Instead | |-------|-----|---------| | Skipping eligibility check | May commit ineligible files with investigation-only skip | Always run the skill before using the skip | | Ignoring violations | QA exemption won't be valid | Address violations or invoke qa agent | | Using for code changes | Investigation-only is for analysis, not implementation | Start a new session for code work | | Hardcoding path checks | Patterns may drift from Validate-SessionJson.ps1 | Use this skill which shares the same patterns |

Verification Checklist

After using this skill:

[ ] Skill output shows Eligible: true
[ ] No Violations in output
[ ] No Error field in output
[ ] Session log evidence updated with skill output

| Reference | Description | |-----------|-------------| | ADR-034 | Investigation Session QA Exemption architecture decision | | SESSION-PROTOCOL.md | Session start/end requirements (Phase 2.5) | | Issue #662 | Create QA skip eligibility check skill | | Validate-SessionJson.ps1 | Uses same allowlist for CI validation | | Test-InvestigationEligibility.Tests.ps1 | Pester tests ensuring pattern consistency |