gabrielmoreira Documentation Sync: Distill Engineering Work to Canonical Documents
1. Ingestion of All Artifacts
The skill MUST scan and parse all files in the active milestones/M{X}/ folder (including specs, verifications, test plan ledgers, completions, evaluations, reviews, and closures) before updating any canonical documents.
2. Surgical Reconcile Duty
Compare completed codebase realities against SPEC.md, DATA.md, PLAYBOOK.md, and CHANGELOG.md to surgically update public class signatures, SQL schemas, and changelog entries.
3. Post-Ingestion Diagram Check (MANDATORY)
Immediately after successfully ingesting and syncing project files, execute the 'diagrammer' command to rebuild the visual index. Diffs of modified diagrams (docs/diagrams/*.mmd) must be presented to the user alongside standard markdown diffs for approval.
Auto-Run After Session Audit
After session-audit completes, sync-documentation automatically runs (shows changes, asks for approval).
Dynamic Internal Path Resolution
When loading static framework assets (templates, contracts), implement a multi-tier path resolution check:
Prefer local dev paths. Do not crash on path resolution failure without attempting all tiers.
Safety & Workflow
Safety:
- Shows diffs before applying (what WILL change)
- Only applies changes if user says "yes"
- Documentation updates are non-destructive (not behavior-changing)
Project Convention Adherence: Respect project conventions and architecture, especially for application projects.
Example Output:
sync-documentation: Reading M2SA3.md...
- Detected 3 documentation changes.
- Identified changes impacting workspace boundary and canonical resolution.
- Proposed changes:
- docs/skills.md:
- Line 15: Added "hotfix-issue" to skills catalog
- Line 42: Added "session-audit" to framework skills
- docs/PLAYBOOK.md:
- Line 120: Added "Every Session Workflow" section
- docs/diagrams/system_snapshot.mmd:
- Regenerated via diagrammer (diff presented for approval)
- Reconciled artifact references using canonical resolution.
sync-documentation: Apply these changes?
Yes, apply all changes
No, skip
No, but apply skills.md only
Custom selection
Selection: 1
Out of Scope (Negative Guardrails)
Strict Milestone and Project Agnosticism:
- All instructions, prompt examples, schemas, and file path descriptions must be written in strictly agnostic terms.
- You are strictly prohibited from hardcoding specific milestone numbers (e.g., 'M10') or sequence IDs (e.g., 'M10S4') inside the prompt instructions.
- You must utilize the standard wildcard notation:
M{X}for milestones,S{Y}for specifications,T{Z}for test plans, andM{X}S{Y}for active sequence identifiers. This ensures the AEF remains 100% portable and reusable across brownfield and greenfield projects.