Reorganize and update .aiwg/ documentation to reflect current project reality
Reorganizes `.aiwg/` documentation to match current code by analyzing git changes. Use when docs feel outdated after development work.
/plugin marketplace add jmagly/ai-writing-guide/plugin install jmagly-utils-plugins-utils@jmagly/ai-writing-guideAnalyze 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.
| 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 |
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)
Find when documentation was last synchronized with code:
Check for alignment marker:
cat .aiwg/.last-alignment 2>/dev/null
Check git log for doc commits:
git log --oneline --since="30 days ago" -- .aiwg/
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
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)
Documents are considered stale if:
References deleted code/features:
Contradicts current implementation:
Outdated planning artifacts:
Superseded documents:
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
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
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
If --dry-run: Display plan and exit.
If --interactive: Prompt for each action.
Otherwise: Execute with specified flags.
# 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
# Only with --delete-stale and confirmation
rm .aiwg/requirements/feature-x-draft.md
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
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
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.
# 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
| 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 |
/workspace-prune-working - Clean up .aiwg/working/ directory/workspace-reset - Wipe .aiwg/ and start fresh/project-status - View current project state