# session

> Skills for session management and protocol compliance including investigation eligibility checking per ADR-034 to determine when QA validation can be skipped.

- Author: Peter Kloss
- Repository: loriensleafs/brain
- Version: 20260120082312
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/loriensleafs/brain
- Web: https://mule.run/skillshub/@@loriensleafs/brain~session:20260120082312

---

---
name: session
description: Skills for session management and protocol compliance including investigation eligibility checking per ADR-034 to determine when QA validation can be skipped.
license: MIT
agents:
  - orchestrator
metadata:
version: 1.0.0
model: claude-sonnet-4-5
---

# 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

---

## Related

| Reference | Description |
|-----------|-------------|
| [ADR-034](../../.agents/architecture/decisions/adr-034-investigation-session-qa-exemption.md) | Investigation Session QA Exemption architecture decision |
| [SESSION-PROTOCOL.md](../../.agents/SESSION-PROTOCOL.md) | Session start/end requirements (Phase 2.5) |
| [Issue #662](https://github.com/rjmurillo/ai-agents/issues/662) | Create QA skip eligibility check skill |
| [Validate-Session.ps1](../../scripts/Validate-Session.ps1) | Uses same allowlist for CI validation |
| [Test-InvestigationEligibility.Tests.ps1](../../tests/Test-InvestigationEligibility.Tests.ps1) | Pester tests ensuring pattern consistency |