workspace-health

What this skill does

<!-- AIWG-SKILL-CALLOUT -->
> **Skill access pattern (post-kernel-pivot, 2026.5+)**
>
> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
>
> ```bash
> aiwg discover "<capability>"
> aiwg show skill <name>
> ```
>
> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).


# Workspace Health Check Skill

Assesses workspace alignment and suggests cleanup or realignment actions at key transition points.

## Kernel Delegation

> As of ADR-021, `workspace-health` delegates structural checks to the semantic memory kernel.

**Delegation pattern**:
1. `workspace-health` retains its consumer-neutral health-check UX
2. Runs `memory-lint` for every installed framework in `.aiwg/frameworks/registry.json`
3. Aggregates results across all consumers into a unified report
4. `aiwg doctor` continues to call this skill unchanged

**Backward compatibility**: No UX changes. Output format unchanged.

@agentic/code/addons/semantic-memory/skills/memory-lint/SKILL.md

## Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

- "do I need to realign" → workspace realignment check
- "is my workspace aligned" → alignment status check
- "cleanup recommendations" → workspace prune suggestions

Auto-triggers:
- After phase transition flow commands complete
- After completing major features or intensive processes

## Trigger Conditions Reference

This skill is commonly invoked:
- At the end of phase transitions (flow commands)
- After completing major features or intensive processes
- When documentation appears out of sync
- Manually via natural language phrases above

## Assessment Checklist

### 1. Working Directory Health

```yaml
checks:
  - name: working_directory_size
    description: Check if .aiwg/working/ has accumulated stale files
    threshold: ">10 files or >1MB"
    action: Suggest /workspace-prune-working

  - name: orphan_drafts
    description: Draft artifacts not linked to requirements
    action: Suggest review or archival

  - name: stale_locks
    description: Lock files older than 24h
    action: Suggest cleanup
```

### 2. Documentation Alignment

```yaml
checks:
  - name: phase_documentation
    description: Current phase docs match project state
    sources:
      - .aiwg/planning/phase-plan-*.md
      - .aiwg/reports/*-completion-report.md
    action: Suggest /workspace-realign if mismatched

  - name: requirement_coverage
    description: All requirements have linked artifacts
    action: Suggest /check-traceability

  - name: architecture_drift
    description: Code diverged from documented architecture
    action: Suggest architecture review or ADR update
```

### 3. Artifact Freshness

```yaml
checks:
  - name: stale_artifacts
    description: Key artifacts not updated in >30 days during active dev
    artifacts:
      - SAD (Software Architecture Document)
      - Risk Register
      - Test Strategy
    action: Flag for review

  - name: completion_markers
    description: Artifacts marked complete but phase still active
    action: Suggest status update
```

## Output Format

```markdown
## Workspace Health Report

**Overall Status**: [Healthy | Needs Attention | Requires Realignment]

### Quick Actions
- [ ] Run `workspace-prune-working` - 15 stale files in working/
- [ ] Review 3 orphaned draft artifacts
- [ ] Update risk register (last modified 45 days ago)

### Detailed Findings

#### Working Directory
- Status: Needs cleanup
- Files: 15 (threshold: 10)
- Oldest: inception-notes-draft.md (created 2024-11-15)
- Recommendation: Promote or archive before next phase

#### Documentation Alignment
- Phase: Construction
- Last phase report: Elaboration completion (2024-12-01)
- Missing: Construction kickoff documentation
- Recommendation: Run `flow-elaboration-to-construction` completion steps

#### Traceability
- Requirements covered: 85%
- Orphan code files: 3
- Recommendation: Run `check-traceability` for details
```

## Integration Points

### Flow Command Endings

Add to flow command templates:

```markdown
## Post-Completion

After this flow completes, consider running a workspace health check:

[workspace-health] Assessing workspace alignment...

If issues found, the skill will suggest appropriate cleanup commands.
```

### Proactive Invocation

The orchestrator should invoke this skill:
1. When transitioning between SDLC phases
2. After completing iteration cycles
3. When user requests project status
4. Before major deployments

## Implementation Notes

This skill should:
1. Read workspace state from `.aiwg/` structure
2. Compare against expected state for current phase
3. Generate actionable recommendations
4. NOT automatically execute cleanup (user confirms)

## Related Commands

- `workspace-prune-working` - Clean up working directory
- `workspace-realign` - Reorganize documentation structure
- `workspace-reset` - Full workspace reset (destructive)
- `project-status` - Current project state
- `check-traceability` - Verify requirement links

## References

- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/README.md — aiwg-utils addon overview
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/human-authorization.md — Report findings and await user authorization before cleanup
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/vague-discretion.md — Concrete thresholds for health checks (file count, age)
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/README.md — SDLC phase structure that workspace health is measured against