self-improve

name	self-improve
description	Introspect on a completed work session to propose and apply improvements to documentation, agent guidance, and repo quality
outputs	[{"name":"improvements","description":"List of proposed changes with rationale, and which were applied"}]

Purpose

Guide end-of-session reflection that turns work context into concrete improvements to documentation and agent guidance. Instead of maintaining a running session log, this skill reconstructs what happened from git state and conversation context, then proposes targeted edits.

Preconditions

• At least one commit exists on the current branch beyond main (or there are uncommitted changes)
• The agent has context from the current conversation about work performed

Steps

1. Gather session context

Reconstruct what happened during the session using git state:

# What files changed
git diff main...HEAD --stat

# Commit history for this branch
git log main..HEAD --oneline

# Uncommitted changes
git diff --stat
git diff --cached --stat

Read the changed files to understand the nature of the work.

Build a mental model of:

Element	Source
What code was added/changed	git diff
Why it was changed	Commit messages + conversation context
What patterns were used	Reading the changed files
What friction was encountered	Conversation context (errors, retries, pivots)

2. Audit documentation freshness

For each file changed, check whether corresponding documentation is stale:

If this changed...	Check these docs...
Routes or services (src/routes/, src/services/)	docs/openapi/ for API spec accuracy, AGENTS.md architecture section
Models or migrations (src/models/, src/migrations/)	docs/tech-stack.md, AGENTS.md database section
Test patterns or helpers	docs/guides/testing.md, best_practices.md testing section
Infrastructure or config (Dockerfile, CI)	docs/guides/infrastructure.md, docs/guides/dev-setup.md
Frontend components or pages	AGENTS.md frontend section
Worker or queue changes	AGENTS.md worker section
New dependencies (package.json)	docs/tech-stack.md
Dev workflow (scripts, Makefile, docker-compose)	docs/guides/yarn-commands.md, docs/guides/dev-setup.md

Read the relevant doc files and compare their descriptions against the current code state.

3. Check for common doc debt signals

Scan documentation files for known debt patterns

Stale references:

• File paths mentioned in docs that no longer exist
• Command examples that reference renamed scripts
• Architecture descriptions that don't match current directory structure

Duplicated content:

• Check for substantially similar paragraphs across AGENTS.md, README.md, and doc files
• Identify content that should live in one place and be referenced from others

Unresolved markers:

grep -rn 'TODO\|TBD\|FIXME\|HACK\|XXX' docs/ AGENTS.md best_practices.md

Check if any of these can now be resolved given the session's work.

4. Review agent guidance gaps

Reflect on the session's conversation context for friction signals:

Friction signal	Potential improvement
Agent had to search extensively for a pattern	Add the pattern to AGENTS.md or best_practices.md
Agent made incorrect assumptions about architecture	Clarify the relevant AGENTS.md section
Agent used a workaround for a known issue	Document the gotcha in the relevant guide
A new convention was established during the session	Capture it in best_practices.md
Agent needed information that wasn't in any doc	Add it to the appropriate file
Agent had to ask for clarification about project norms	Document the answer for future sessions
Testing required unexpected setup or teardown	Add to docs/guides/testing.md

5. Propose improvements

Present a numbered list of proposed changes. Each proposal should include:

### Proposal N: [Brief title]

- **Target file:** `path/to/file.md`
- **Category:** [docs-freshness | broken-link | duplicate-content | new-pattern | agent-guidance | stale-reference]
- **What:** [Specific change to make]
- **Why:** [Rationale tied to session context or audit finding]

Categories explained:

Category	Meaning
docs-freshness	Documentation doesn't match current code state
broken-link	A relative link points to a file that doesn't exist
duplicate-content	Same information repeated across multiple files
new-pattern	A pattern or convention established during the session worth capturing
agent-guidance	Missing or misleading guidance in agent-facing files
stale-reference	Doc references a file, command, or concept that no longer exists

If no improvements are found, state "No improvements identified" with a brief explanation of what was checked.

6. Apply approved changes

Ask the user which proposals to apply:

• "Apply all" — edit all target files
• Selective — apply only chosen proposals
• "None" — skip application, keep proposals as a record

For each approved proposal, edit the target file directly. Keep changes minimal and focused — don't rewrite entire sections when a sentence fix suffices.

7. Summary

Output a final summary:

## Session Reflection Summary

### Applied
- [List of proposals that were applied, with file paths]

### Deferred
- [List of proposals not applied, with brief reason]

### Session stats
- Files changed this session: N
- Docs checked: N
- Proposals generated: N
- Proposals applied: N

Completion Criteria

• Git diff and log were reviewed for the session's changes
• Documentation files were checked for staleness against code changes
• Broken links, duplicates, and stale references were scanned for
• Agent guidance was reviewed for gaps based on session friction
• At least one proposal was generated (or an explicit "nothing to improve" finding)
• Approved proposals were applied to the target files