workspace-consistency — Workspace Consistency Check & End-of-Work Orchestration

When to use

• Wrapping up a piece of work (feature complete / milestone complete / before ending a session).
• Before starting new dev, confirm the workspace is clean.
• The user asks "anything left to sync or archive?", "is the workspace clean?", "confirm no legacy".

When NOT to use

• In-flight feature work — this is an end-of-work checkpoint, not a development tool.
• Single-dimension deep dive (e.g., only want repo hygiene) — invoke the specialized skill directly.

How this differs from related skills (avoid overlap)

• change-recap — extracts and sediments knowledge after work (recurring pitfalls / reusable patterns) — knowledge layer.
• phase-tracking — executes updates to the progress-tracking doc; readme-sync — executes updates to onboarding docs — executors.
• This skill — audits "are docs outdated / is code synced / are changes recorded / is there legacy", and routes to the skills above when something fails. It does not duplicate their work.
• At wrap-up, all three may run: first this skill audits consistency → route to the right skill to fix → finally change-recap sediments knowledge.

Output

A four-dimension audit table (each dimension: pass / fail + evidence) + an orchestration todo list (each fail → corresponding fix action). All four pass = workspace clean.

Methodology: four-dimension audit

Suggested order: "traceable → docs synced → no legacy → repo clean" (first confirm all changes are recorded, then docs can catch up), but the order is not mandatory.

Dimension 1: Changes traceable

• List the code changes produced in this work; for each, check whether there is a matching change record (change archive / PR / issue).
• Audit question: "Are there any bare changes — code modified but no record left behind?"
• Typical fail: a batch of code is done and tests pass, but there is no matching change record (after-the-fact archive scenario).

Dimension 2: Docs synced with code

Audit whether four categories of docs reflect the current state of the code:

• Progress-tracking docs (stage progress / tech decisions): are progress markers stale (marked "todo" but actually done; marked "not archived" but actually archived)?
• Spec docs (system contracts / behavior): is the described approach still the one the code uses (doc says A, code switched to B)?
• Onboarding docs (README / new-hire guides): are they outdated?
• Review checklists / selection decision docs (code-review.md, ADRs, decision records): ⚠ their rule-style items ("must do X / must not do Y") upgrade from "stale description" to "wrong review basis" after architecture or contract changes — more dangerous than ordinary staleness, they mislead future PR reviews. After architectural changes, scan these docs first for rule items.
• Audit question: "Does the doc's described state (especially rule items) still match the code?"
• Typical fail: spec docs lag the code by a step or two; after an architecture change, the review checklist still lists old-model rules (e.g., transport switched from dual-channel to single-channel, but the checklist still requires "emergency stop on a dedicated reliable channel" → misleading review).

Dimension 3: No legacy → follow legacy-code-disposition

Audit for dead code / half-finished work / disconnected logic / long-standing TODOs / uncertain code. Disposition decisions (delete / wire up / preserve with contingency) follow the legacy-code-disposition methodology; this skill does not duplicate it.

Dimension 4: Repo clean → follow repo-hygiene

Audit whether the working tree is clean, whether anything improper slipped into the repo (third-party / large files / nested repos / local config), whether commit granularity is reasonable, and whether ignore rules are working. Cleanup follows the repo-hygiene methodology; this skill does not duplicate it.

Orchestration (fail → action mapping)

After fixes, re-audit the failing dimension to confirm it passes (re-verify; do not just check once).

Clean criterion

All four dimensions pass = workspace clean, can start new dev. If any fail, fix first, then re-confirm.

Red lines (reasoned, not absolute)

• Do not skip the audit and dive into new dev — at least a quick pass through the four dimensions before starting work, so that you do not build on stale state.
• Do not write execution actions into this skill — keep it a pure ledger layer; execution belongs to the referenced skills (otherwise this skill drifts out of sync with the source methodologies).
• Do not audit without re-verifying — after fixes, re-run the audit to confirm the dimension passes; "checked once" is not enough.

Worked example: one full audit (sanitized)

The user asked twice "anything left to sync or archive, confirm the workspace is clean", and all four dimensions hit:

1. Changes traceable: a batch of code changes (video reception + signaling-layer refactor) had no change record → retroactively archived a change.
2. Docs synced: spec doc described the old signaling approach while code had switched → caught up to the main spec; progress doc marked "a flow not archived" while it actually was → fixed the stale wording.
3. No legacy: found a stretch of "decided not to use it" code → routed to legacy-code-disposition, decided to delete.
4. Repo clean: found a large batch of improperly committed third-party files (already tracked, ignore ineffective) + nested repo + local config → routed to repo-hygiene for cleanup.

After fixes, all four passed on re-audit; working tree clean; workspace clean.

This is one instance, not the methodology itself.