sync-docs

name	sync-docs
description	Sync tracking documents based on current conversation results. Updates subtask, progress, findings, task_plan, project CLAUDE.md. Use when finishing a task or reaching a milestone.
argument-hint	[archive|park]

autoworker:sync-docs — Sync Tracking Documents

Based on work results and discoveries in the current conversation, update all tracking documents.

Input

Optional argument: $ARGUMENTS

• No argument: Sync only (check off items, record progress, add findings, audit claude_docs)
• park: Sync + pause current subtask (set status: paused) + clear plan file. For "task still in progress (e.g., training) but need to switch to something else"
• archive: Sync + archive completed subtask (move to claude_docs/subtask/) + clear plan file. For "task fully complete"

Execution Flow

1. Scan Current State

Find tracking files and document system in the project root:

Top-level tracking files:

• subtask_*.md — current in-progress subtasks
• progress.md — progress log
• findings.md — core discoveries
• task_plan.md — task planning
• Project-level CLAUDE.md — project rules and technical info
• README.md — project intro (for humans)

Progressive disclosure documents:

• claude_docs/reference/*.md — detailed documents referenced from CLAUDE.md
• Subdirectory CLAUDE.md — index files for each module

Read each existing file to understand current recorded state.

2. Compare Against Conversation Content

Review work completed in this conversation, determine updates needed item by item:

File	Update condition	Update content
subtask_*.md	Steps were completed	Check off [x], record progress, add verification results
progress.md	Task completed or progressed	Update task item status, add result summary
findings.md	New conclusions or counter-intuitive behaviors discovered	Add new section or update existing section
task_plan.md	Task completed/progressed, or plan changed	Read subtask's "task_plan positioning → corresponding Phase" field, locate and check off [x] in task_plan.md with completion timestamp; match by content when no positioning field; update future steps if plan changed
CLAUDE.md	Reusable patterns or lessons learned discovered	Add to appropriate section (don't duplicate existing content)
claude_docs/reference/*.md	Findings in this conversation belong to an existing reference topic	Update corresponding reference document
Subdirectory CLAUDE.md	Changed code structure/files in a module	Update corresponding subdirectory file index
README.md	Added feature or changed usage/installation	Sync update (user-perceivable changes)

2.5. Reference Document Consistency Check

Dead link check: Scan project CLAUDE.md for all claude_docs/reference/ references, confirm files exist:

• Referenced file exists → OK
• Referenced file doesn't exist → report dead link, suggest creating or fixing reference

New reference identification: If this conversation produced new lessons or technical documentation (> 20 lines) and CLAUDE.md already exceeds 300 lines, suggest writing to claude_docs/reference/<topic>.md and adding a trigger heading in CLAUDE.md, rather than appending directly to CLAUDE.md.

3. Execute Updates

For each file needing update:

• Read current content first
• Use Edit for precise updates (don't rewrite entire file)
• Briefly describe what changed after each update

3.5. claude_docs/ Subdirectory Recursive Audit

Using claude_docs/ progressive disclosure structure, check if this conversation's changes affect subdirectory documents:

Flow:

1. Glob claude_docs/*/CLAUDE.md → get all subdirectory indexes
2. Read each subdirectory CLAUDE.md (it's the semantic index listing files and purposes)
3. Compare against this conversation's changes:
   • Files in this subdirectory were modified? → update corresponding index entry
   • This subdirectory's topic was affected (e.g., new archived subtask, modified reference)? → update index
   • New files should be added to index? → add
   • Old files should be removed from index? → remove
4. Skip unaffected subdirectories — no need to update everything

4. park (only when argument includes "park")

Pause the current active subtask, clean up workspace, facilitate switching to next task. Subtask file stays in workspace (not archived) and can be resumed later.

1. Glob subtask_*.md → grep status: active → Edit to status: paused
2. Append pause reason in the paused subtask's progress log: **Paused** — <infer reason from conversation, e.g., "waiting for training completion">
3. Clear plan file (same logic as archive)
4. Record pause status in progress.md

5. archive (only when argument includes "archive")

Status filter:

1. Glob subtask_*.md (exclude subtask_template.md) → grep status: to filter
2. Only archive subtasks with status: completed
3. None completed → report "no completed subtask to archive", skip remaining steps
4. Mixed status → report which were archived, which retained (and why: active/paused/no status field)

Execute archive (for each completed subtask):

1. Determine sequence number: read claude_docs/subtask/CLAUDE.md to find max sequence + 1
2. Copy file: subtask_<name>.md → claude_docs/subtask/<sequence>_<name>_<date>.md
3. Delete workspace original: rm subtask_<name>.md (after archiving, don't keep in workspace — prevents dispatch from selecting it next time)
4. Update indexes:
   • claude_docs/subtask/CLAUDE.md archive list + Phase grouping
   • progress.md add archive link
5. Clear plan file: Glob .claude/plans/*.md, find current project's plan file, clear contents (write empty string). Archiving = task done — stale plan would interfere with next autoworker:deep-plan.

6. Project CLAUDE.md Health Check

Check project-level CLAUDE.md size and structure (if exists):

Size check:

• <= 300 lines → healthy
• 301-500 lines → getting large, suggest organizing

• 500 lines → bloated, list content that can be migrated

Bloat identification (when > 300 lines):

Scan CLAUDE.md sections, identify migratable content by these rules:

Pattern	Should migrate to	How to detect
Experiment logs, hyperparameter comparison tables	progress.md	Contains epoch/loss/reward numeric tables
Bug fix history, lessons learned (> 20 lines)	findings.md or claude_docs/reference/	Detailed content > 20 lines
Detailed data pipeline documentation	claude_docs/reference/data_pipeline.md	Data formats, field descriptions, transformation flows
Detailed API/config documentation	claude_docs/reference/<topic>.md	Detailed config item lists or code templates

Output:

• Healthy → report "CLAUDE.md: N lines, healthy"
• Bloated → list section line counts + migration suggestions (don't auto-migrate, just report)

7. Git Commit (only when argument includes "park" or "archive")

After park or archive completes, commit and push all changes to remote.

8. Output Summary

List all updated files and change highlights:

sync-docs complete:
- subtask_xxx.md: Steps 3-5 checked off, verification results added
- progress.md: Task X marked complete
- CLAUDE.md: Added "YYY" lesson
- [archive] → claude_docs/subtask/40_xxx_20260227.md
- CLAUDE.md health: N lines, healthy / getting large, suggest migrating X sections

Important Notes

• Don't fabricate content: Only update based on what actually happened in the conversation — don't write uncertain things
• CLAUDE.md updates should be cautious: Only add verified, reusable patterns — not one-time details
• Don't create non-existent files: If the project doesn't have findings.md, don't create it (unless the conversation has clear new findings needing recording)
• archive condition is status: completed: Only subtasks with completed status (after gate-check PASS) get archived