/workspace-health

namespace: aiwg
name: workspace-health
platforms: [all]
description: Assess workspace alignment and recommend cleanup or realignment actions at key lifecycle transition points

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

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

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