diff --git a/.pi/skills/retrospect b/.pi/skills/retrospect new file mode 120000 index 0000000..e35050d --- /dev/null +++ b/.pi/skills/retrospect @@ -0,0 +1 @@ +../../src/skills/retrospect \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 1e26156..ade059f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,20 +67,6 @@ after applying an accepted change. If the workflow is paused, say that plainly instead of using a dangling transition like "continuing" or "next". -## Corrections - -- When you discover that your belief about a project fact or convention was wrong, record the correction. - Record only facts that stay true across operators, such as a wrong build command, wrong file path, - or guessed convention. - Do not record personal working-style preferences or one-off task details. -- Record the correction in the nearest project `AGENTS.md`. - Use a dedicated `## Gotchas` section. - Create that section when the file lacks one. -- If no project `AGENTS.md` exists, ask before creating one. - Append the correction immediately without asking when a project `AGENTS.md` exists. - Briefly mention the edit in your response. - If an existing entry is wrong or stale, correct or remove it the same way. - ## Gotchas - When materializing an external specification, standard, or project-maintained convention, use the diff --git a/src/skills/retrospect/SKILL.md b/src/skills/retrospect/SKILL.md new file mode 100644 index 0000000..da64e65 --- /dev/null +++ b/src/skills/retrospect/SKILL.md @@ -0,0 +1,44 @@ +--- +name: retrospect +description: "Conduct a retrospective on a coding session." +disable-model-invocation: true +--- + +The user has asked for a **retrospective**. You are suggesting improvements to the coding agent's **environment** to improve future runs. + +## Steps + +1. Read [`../agent-writing-guide/SKILL.md`](../agent-writing-guide/SKILL.md). + +2. Read the primary sources for the session the user specifies. This may mean searching through session logs on this machine. If the user doesn't specify a session, default to the current one. + +3. Look for candidates for improvement in these categories. + +- **Navigation**: how easy was it for the agent to find the right files? Are there hidden dependencies between files? Would a **navigation pointer** make it easier? _Use when_ the session took a long time to find a piece of information. +- **Automated checks**: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? Read the repo's own check command first (its `package.json`/build-tool `lint`/`check` scripts, its CI workflow), so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. A repo with no **guardrail** (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding: an un-linted repo is a standing missed opportunity, not a neutral default. _Use when_ the agent made a mistake an automated check could have caught, or the repo has no guardrail at all. +- **Coding standards**: should the **reviewer agent** be given a new rule to enforce? Should an existing rule be removed or clarified? Classify the violation first: a **mechanical** one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop: a custom rule in the repo's own linter, a new pre-commit hook, or a new CI job, whichever the repo's language and existing guardrail make cheapest. Default to building the check over writing the rule. Reserve **review standards** for genuine **judgement calls** (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). Before proposing a rule, identify the repository source that its review workflow loads. Keep the rule in that established source. _Use when_ the reviewer agent failed to catch a mistake. +- **Global AGENTS.md**: are there any steering instructions that should be moved to review standards (or automated checks) instead? _Use when_ the AGENTS.md file is particularly large - in the repo OR the user's global scope. +- **Tool economy**: did the agent make expensive tool calls that could be streamlined? Is there any custom tooling (CLI's, MCP's) that is particularly token-inefficient? _Use when_ the agent made an expensive tool call. +- **No-ops**: look for instructions in steering files that don't modify the agent's behavior. _Use when_ the steering files are large and unwieldy. +- **Information access**: look for opportunities to increase the agent's access to information. Teeing dev server logs, readonly access to third-party services. _Use when_ a crucial piece of information was not available to the agent. + +4. Present these candidates to the user, in order of severity. + +## Reference + +### Implementation vs Review + +Remember that all work goes through two stages: implementation and review. The implementation agent has the most **context pressure**. They are responsible for exploration, writing code, and debugging failures. + +The review agent has the least context pressure - it receives a diff, so no exploration needed. It often does not need to write code or debug. + +This means that the review agent should be responsible for imposing coding standards, not the implementation agent. + +### Files + +You have access to several files in the repo: + +- `AGENTS.md`: these files are pushed to the context window of any agent working in this repo. They should be used incredibly sparingly, usually only for **navigation pointers** to other files. +- **Review standards**: these are the documented rules that the repository's review workflow loads. They can live in a standards file, a contribution guide, or scoped rule files. Find the existing source before proposing an addition. +- Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones. +- Skills: use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the `agent-writing-guide` skill.