# State Manager

> Specialized in maintaining project logs, tracking decisions, and validating implementation against original specifications. Use when documenting decisions, maintaining project history, validating work completeness, auditing implementation, or tracking project state.

- Skill: `karim-bhalwani/state-manager` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add karim-bhalwani/state-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/karim-bhalwani/state-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: karim-bhalwani (https://skillmd.com/u/karim-bhalwani)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/karim-bhalwani/state-manager

---


# 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

| Phase | Input From | Output To | Context |
|-------|-----------|-----------|---------|
| Task Completion | Feature complete | Closure report | Compare against `spec.md`, log test results |
| Decision Logging | Architectural choice | `decisions.md` update | Record what was decided and context |
| Compliance Check | Implementation ready | Adherence scorecard | Verify requirements met, flag gaps |
| Handoff | Work done | Next phase gate | Provide evidence for approval before proceeding |