/workspace-realign

namespace: aiwg
name: workspace-realign
platforms: [all]
description: Reorganize and update .aiwg/ documentation to reflect current project reality

Workspace Realign

Analyze and reorganize documentation in `.aiwg/` to ensure it accurately reflects the current project state, plans, and reality. Uses git commit history to understand changes since documentation was last updated.

Parameters

| Flag | Description | |------|-------------| | `project-directory` | Project root (default: `.`) | | `--archive-stale` | Move stale documents to `.aiwg/archive/` instead of deleting | | `--delete-stale` | Delete stale documents (requires confirmation) | | `--dry-run` | Preview changes without modifying files | | `--since <commit>` | Analyze changes since specific commit (default: last doc update) | | `--interactive` | Prompt for each decision |

Execution Steps

Step 1: Analyze Current State

Scan `.aiwg/` directory structure:

# Count documents by category
find .aiwg -name "*.md" -type f | wc -l

# Get last modification times
find .aiwg -name "*.md" -type f -exec stat -c '%Y %n' {} \; | sort -rn

Report current state:

Workspace Analysis
==================
Total documents: 47
Categories:
  - requirements/    12 docs
  - architecture/     8 docs
  - planning/         6 docs
  - risks/            4 docs
  - testing/          5 docs
  - security/         3 docs
  - working/          9 docs (temporary)

Step 2: Identify Last Documentation Alignment

Find when documentation was last synchronized with code:

1. **Check for alignment marker:**

   cat .aiwg/.last-alignment 2>/dev/null

2. **Check git log for doc commits:**

   git log --oneline --since="30 days ago" -- .aiwg/

3. **Find most recent doc update:**

   git log -1 --format="%H %ci" -- .aiwg/

Report:

Last Alignment
==============
Last doc commit: abc1234 (2025-12-01)
Current HEAD:    def5678
Commits since:   23 commits
Days since:      8 days

Step 3: Analyze Code Changes Since Last Alignment

Compare code changes vs documentation:

# Get changed files since last alignment
git diff --name-only <last-alignment-commit>..HEAD

# Categorize changes
git diff --stat <last-alignment-commit>..HEAD

**Change Categories:**

| Change Type | Doc Impact | |-------------|------------| | New features | Requires new requirements/arch docs | | Refactoring | May invalidate architecture docs | | API changes | API docs need update | | Test changes | Test strategy may need update | | Security changes | Security docs may be stale | | Deleted code | Related docs may be obsolete |

Report:

Code Changes Analysis
=====================
Since: abc1234 (2025-12-01)

Feature Changes (5):
  + src/auth/oauth.ts (new)
  + src/auth/jwt.ts (new)
  ~ src/api/endpoints.ts (modified)
  ~ src/models/user.ts (modified)
  - src/legacy/old-auth.ts (deleted)

Impacted Documentation:
  - .aiwg/requirements/user-stories.md (user auth stories)
  - .aiwg/architecture/api-design.md (endpoint changes)
  - .aiwg/security/auth-strategy.md (new auth methods)
  - .aiwg/architecture/legacy-support.md (deleted code)

Step 4: Identify Stale Documents

Documents are considered stale if:

1. **References deleted code/features:**

• Mentions files that no longer exist
• References APIs that were removed

2. **Contradicts current implementation:**

• Architecture describes different structure
• Requirements don't match actual behavior

3. **Outdated planning artifacts:**

• Completed iteration plans
• Resolved risk items
• Closed decision records

4. **Superseded documents:**

• Earlier versions of refined docs
• Draft documents that became final

**Stale Detection Heuristics:**

# Find docs referencing deleted files
for doc in .aiwg/**/*.md; do
  # Extract file references from doc
  grep -oE 'src/[a-zA-Z0-9_/.-]+' "$doc" | while read ref; do
    [ ! -e "$ref" ] && echo "STALE: $doc references missing $ref"
  done
done

# Find docs with old terminology
grep -r "deprecated_feature" .aiwg/

# Find completed iteration plans
grep -l "Status: Completed" .aiwg/planning/iteration-*.md

Report:

Stale Document Analysis
=======================

DEFINITELY STALE (3):
  .aiwg/architecture/legacy-support.md
    - References deleted: src/legacy/old-auth.ts
    - Last updated: 45 days ago
    Recommendation: ARCHIVE or DELETE

  .aiwg/planning/iteration-3-plan.md
    - Status: Completed
    - All items delivered
    Recommendation: ARCHIVE

  .aiwg/requirements/feature-x-draft.md
    - Superseded by: feature-x-final.md
    Recommendation: DELETE

POSSIBLY STALE (2):
  .aiwg/architecture/api-design.md
    - References modified: src/api/endpoints.ts
    - May need update
    Recommendation: REVIEW

  .aiwg/risks/performance-spike.md
    - Linked PoC completed
    - Risk may be retired
    Recommendation: REVIEW

Step 5: Identify Missing Documentation

Based on code changes, identify gaps:

# New features without docs
for feature in $(git diff --name-only --diff-filter=A <since>..HEAD | grep -E '^src/'); do
  # Check if any doc references this file
  grep -l "$feature" .aiwg/**/*.md 2>/dev/null || echo "UNDOCUMENTED: $feature"
done

Report:

Documentation Gaps
==================

New Code Without Documentation:
  src/auth/oauth.ts
    - No architecture doc
    - No security review
    Recommendation: Create .aiwg/architecture/oauth-integration.md

  src/auth/jwt.ts
    - No architecture doc
    Recommendation: Add to .aiwg/security/auth-strategy.md

Modified APIs Without Doc Updates:
  src/api/endpoints.ts (47 lines changed)
    - .aiwg/architecture/api-design.md not updated since changes
    Recommendation: Update API documentation

Step 6: Generate Update Plan

Create prioritized action plan:

Workspace Realignment Plan
==========================

IMMEDIATE ACTIONS (blocking accuracy):

1. UPDATE: .aiwg/architecture/a