retro — shipwithian/shipkit-core

The user has asked for a **retrospective**. You are suggesting improvements to the coding agent's **environment** to improve future runs. ## Steps 1. Call the Skill tool with `writing-for-agents` for the writing style guide. 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? This repo's guardrail is `composer ci:check` (Rector, `vp check`, `tsc`, Pint, PHPStan, Pest), run by `.github/workflows/tests.yml`, and its architecture checks live in `vendor/shipwithian/shipkit-core/tests/ArchitectureTest.php`. Read them first, so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. Check `.ai/rules/enforcement.md` for rules that nothing enforces yet. _Use when_ the agent made a mistake an automated check could have caught. - **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 the `.ai/rules` files for genuine **judgement calls** (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). _Use when_ the reviewer agent failed to catch a mistake. - **Always-loaded guidelines**: `CLAUDE.md` and `AGENTS.md` are generated by `php artisan boost:update` from `.ai/guidelines/`, `shipkit-core`'s guidelines, and Boost's package guidelines, so edit `.ai/guidelines/` (or `shipkit-core` in ShipKit itself), never the generated files. Are there steering instructions there that should move to a glob-scoped `.ai/rules` file (or an automated check) instead? _Use when_ the generated file is particularly large. - **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. The Laravel Boost MCP tools (`last-error`, `read-log-entries`, `browser-logs`, `database-query`, `database-schema`, `search-docs`) are the first place to look. _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: - `.ai/guidelines/*.md`: compiled into `CLAUDE.md`/`AGENTS.md`, so they are pushed to the context window of every agent. Use them incredibly sparingly, mostly for **navigation pointers** to other files. - `.ai/rules/*.md`: scoped by `paths:` globs and mapped in `.ai/rules/index.md`; agents read the ones matching the files they touch. The context rule files in `.ai/rules/contexts/` hold each context's vocabulary and invariants. `/review-diff` reads these as the standards. - `.ai/rules/enforcement.md`: pairs each rule with the check that enforces it. - Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones. - Skills: live in `.ai/skills/` (the project's) and `vendor/shipwithian/shipkit-core/resources/boost/skills/` (shared), and are synced to every agent by `php artisan boost:update`. Use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the `writing-for-agents` skill.

The user has asked for a retrospective. You are suggesting improvements to the coding agent's environment to improve future runs.

Steps

Call the Skill tool with writing-for-agents for the writing style guide.
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.
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? This repo's guardrail is composer ci:check (Rector, vp check, tsc, Pint, PHPStan, Pest), run by .github/workflows/tests.yml, and its architecture checks live in vendor/shipwithian/shipkit-core/tests/ArchitectureTest.php. Read them first, so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. Check .ai/rules/enforcement.md for rules that nothing enforces yet. Use when the agent made a mistake an automated check could have caught.
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 the .ai/rules files for genuine judgement calls (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). Use when the reviewer agent failed to catch a mistake.
Always-loaded guidelines: CLAUDE.md and AGENTS.md are generated by php artisan boost:update from .ai/guidelines/, shipkit-core's guidelines, and Boost's package guidelines, so edit .ai/guidelines/ (or shipkit-core in ShipKit itself), never the generated files. Are there steering instructions there that should move to a glob-scoped .ai/rules file (or an automated check) instead? Use when the generated file is particularly large.
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. The Laravel Boost MCP tools (last-error, read-log-entries, browser-logs, database-query, database-schema, search-docs) are the first place to look. Use when a crucial piece of information was not available to the agent.

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:

.ai/guidelines/*.md: compiled into CLAUDE.md/AGENTS.md, so they are pushed to the context window of every agent. Use them incredibly sparingly, mostly for navigation pointers to other files.
.ai/rules/*.md: scoped by paths: globs and mapped in .ai/rules/index.md; agents read the ones matching the files they touch. The context rule files in .ai/rules/contexts/ hold each context's vocabulary and invariants. /review-diff reads these as the standards.
.ai/rules/enforcement.md: pairs each rule with the check that enforces it.
Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones.
Skills: live in .ai/skills/ (the project's) and vendor/shipwithian/shipkit-core/resources/boost/skills/ (shared), and are synced to every agent by php artisan boost:update. Use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the writing-for-agents skill.