name: workspace-health-check-skill description: Assesses workspace alignment and suggests cleanup or realignment actions at key transition points. Use when relevant to the task.

Workspace Health Check Skill

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

Trigger Conditions

This skill should be invoked:

• At the end of phase transitions (flow commands)
• After completing major features or intensive processes
• When documentation appears out of sync
• Manually via "check workspace health" or similar

Natural Language Triggers

• "check workspace health"
• "is my workspace aligned"
• "workspace status"
• "do I need to realign"
• "cleanup recommendations"

Assessment Checklist

1. Working Directory Health

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

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

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

## 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:

## 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