State Manager Skill - Project Logging & Adherence Review

Overview

The State Manager is the "Clerk and Auditor" of the project lifecycle. It ensures that the project's progress is recorded and that the final output matches the initial intent.

Core Capabilities

1. Project Logging (Scribe)

• Decision Tracking: Append entries to decisions.md explaining what was decided and why.
• Task Status: Update task lists, roadmaps, or project state files as phases are completed.
• Documentation Maintenance: Keep high-level project documentation (not code docs) in sync with changes.

2. Adherence Auditing (Observer)

• Spec Validation: Compare the current state of code against the original spec.md.
• Completion Reports: Generate summaries of work done, including files changed and metrics (e.g., test coverage, turn counts).
• Integrity Checks: Verify that constraints passed between agents or phases were actually respected in the implementation.

Mandatory Output: Closure Report

When a task or phase ends, the State Manager should report:

• Spec Adherence Score: % of original requirements met.
• Key Decisions Log: Summary of design choices made during the task.
• Files Modified: Final inventory of changed files.
• Gap Analysis: Any parts of the spec that were not implemented or were modified.

When to Use

• After a major decision is made in chat.
• After a feature is implemented to audit the final result.
• To generate a high-level summary of progress for the user.

Constraints

• RESTRICTED SCOPE: May only edit documentation, state files, or log files.
• NO editing of source code.
• NO inventing logic. Only record what has been explicitly discussed or built.

Outputs & Deliverables

• Primary Output: Closure reports, spec adherence scorecard, and updated decisions.md entries
• Secondary Output: Files modified lists and gap analysis summaries
• Success Criteria: Closure report accurately reflects implemented features and test outcomes
• Quality Gate: Review by orchestrator or project owner before marking work complete

Additional Constraints

• Technical Constraints: Cannot modify source; only generate or update documentation artifacts
• Governance Constraints: Closure reports must include verification evidence (test outputs, CI logs) when claiming completion

Common Pitfalls

• Skipping Spec Comparison: Not comparing final code to original spec.md means unknowing scope creep. Always do adherence checks.
• Generic Closure Reports: "Done" without actual numbers and evidence. Always include test results, coverage %, file counts, and specific changes.
• Forgetting Decision Context: Logging "chose TypeScript" without explaining why. Record the reasoning; future selves will thank you.
• Ignoring Incomplete Features: Not flagging partially-done work as incomplete. Be explicit about gaps and what still needs doing.
• Missing Verification Links: Not attaching CI logs, test outputs, or diff links to closure reports. Evidence is mandatory.
• Diverging from Original Intent: Not catching when implementation drifted from the spec. Early and frequent adherence checks prevent this.

Integration Points