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/api-design.md
   Reason: API endpoints changed significantly
   Changes: Add new endpoints, remove deprecated ones

2. UPDATE: .aiwg/security/auth-strategy.md
   Reason: New OAuth/JWT implementation
   Changes: Document new auth flows

3. ARCHIVE: .aiwg/architecture/legacy-support.md
   Reason: Legacy code deleted
   Target: .aiwg/archive/architecture/

4. ARCHIVE: .aiwg/planning/iteration-3-plan.md
   Reason: Iteration completed
   Target: .aiwg/archive/planning/

RECOMMENDED ACTIONS (quality improvement):

5. CREATE: .aiwg/architecture/oauth-integration.md
   Reason: New feature without documentation

6. REVIEW: .aiwg/risks/performance-spike.md
   Reason: May be resolved

7. DELETE: .aiwg/requirements/feature-x-draft.md
   Reason: Superseded by final version

Step 7: Execute Actions

If --dry-run: Display plan and exit.

If --interactive: Prompt for each action.

Otherwise: Execute with specified flags.

Archive Operations

# Create archive directories
mkdir -p .aiwg/archive/{requirements,architecture,planning,risks,testing,security}

# Move with timestamp
mv .aiwg/architecture/legacy-support.md \
   .aiwg/archive/architecture/legacy-support-20251209.md

# Add archive index entry
echo "| 2025-12-09 | legacy-support.md | Deleted legacy code | architecture/ |" \
  >> .aiwg/archive/INDEX.md

Delete Operations

# Only with --delete-stale and confirmation
rm .aiwg/requirements/feature-x-draft.md

Update Operations

For documents needing updates, launch appropriate agent:

Launching documentation update agents...

Task(technical-writer):
  Target: .aiwg/architecture/api-design.md
  Context: src/api/endpoints.ts changes
  Action: Update API documentation with new endpoints

Task(security-architect):
  Target: .aiwg/security/auth-strategy.md
  Context: src/auth/ new implementation
  Action: Document OAuth/JWT authentication flows

Step 8: Record Alignment

Create alignment marker for future reference:

# Record current HEAD as aligned
echo "$(git rev-parse HEAD) $(date -Iseconds)" > .aiwg/.last-alignment

# Create alignment log entry
cat >> .aiwg/.alignment-log <<EOF
---
date: $(date -Iseconds)
commit: $(git rev-parse HEAD)
actions:
  - archived: 2
  - updated: 2
  - created: 1
  - deleted: 1
  - reviewed: 1
EOF

Step 9: Report Summary

Workspace Realignment Complete
==============================

Actions Taken:
  Archived:  2 documents
  Updated:   2 documents (agents launched)
  Created:   1 document (agent launched)
  Deleted:   1 document
  Reviewed:  1 document (marked for review)

Alignment Recorded:
  Commit: def5678
  Time:   2025-12-09T10:23:45

Next Steps:
  - Review agent-generated updates
  - Check .aiwg/archive/INDEX.md for archived docs
  - Address reviewed items in next session

Run '/workspace-realign --dry-run' periodically to check alignment.

Examples

# Preview what would change
/workspace-realign --dry-run

# Archive stale docs, don't delete
/workspace-realign --archive-stale

# Interactive mode - decide each document
/workspace-realign --interactive

# Check changes since specific commit
/workspace-realign --since abc1234

# Full cleanup with deletions
/workspace-realign --archive-stale --delete-stale

Error Handling

Condition	Action
No .aiwg/ directory	Error: "No .aiwg/ directory found. Initialize with /intake-wizard"
No git repository	Warning: "Not a git repo. Skipping change analysis."
No docs found	Info: "No documentation to realign. Workspace is empty."
Agent launch fails	Continue with next action, report failures at end
Archive exists	Append timestamp suffix to avoid overwrite

Related Commands

• /workspace-prune-working - Clean up .aiwg/working/ directory
• /workspace-reset - Wipe .aiwg/ and start fresh
• /project-status - View current project state

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 — Confirm before archiving or deleting stale documents
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/research-before-decision.md — Analyze git history and doc state before generating update plan
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/README.md — SDLC artifact structure used to assess documentation alignment