Session Skills

Skills for session management and protocol compliance.

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.

Triggers

•"Check if I can skip QA"
•"Am I eligible for investigation-only?"
•"Verify investigation session eligibility"
•"Can I use SKIPPED: investigation-only?"

Usage

powershell

pwsh .claude/skills/session/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):

json

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

Not eligible (contains code files):

json

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

Git error:

json

{
  "Eligible": false,
  "StagedFiles": [],
  "Violations": [],
  "AllowedPaths": [
    ".agents/sessions/",
    ".agents/analysis/",
    ".agents/retrospective/",
    "notes/",
    ".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:

text

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

text

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

2. Run eligibility check
   │
   └── pwsh .claude/skills/session/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:

markdown

### 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
`notes/`	Cross-session context storage (Brain)
`.agents/security/`	Security assessments and reviews

Important: This allowlist MUST match exactly with scripts/Validate-Session.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-Session.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-Session.ps1	Uses same allowlist for CI validation
Test-InvestigationEligibility.Tests.ps1	Pester tests ensuring pattern consistency

Session Skills

Quick Reference

Test Investigation Eligibility

Triggers

Usage

Output

Exit Codes

Error Handling

Example Outputs

Agent Workflow Integration

SESSION-PROTOCOL.md Relationship

Workflow: Before Committing Investigation Work

Integration with Session End Checklist

Allowed Paths (Investigation Allowlist)

Anti-Patterns

Verification Checklist

Related