Software-Engineering on Lessons learned

A repeatable agentic development workflow: context, tickets, implementation, review

Sun, 25 Oct 2026 18:25:00 +0100

Giving a coding agent a feature request and accepting the first working diff is easy. Repeating that across projects is where things get messy: the agent has to rediscover the domain, invent missing requirements, decide what “done” means, and review its own assumptions.

Here is the setup I now reuse across stacks. It has supported ten iOS app releases this year, helped clean up an existing app built with loose agent guidance, and helped a Go implementation recover after its first approach fell apart - to name a few examples. The Go work also involved a language stack and MCP technology I had not used before. The process didn’t provide that expertise on its own; it made the gaps visible early enough to address them.

Give the agent durable context

Start with mattpocock/skills and run its repository setup. Keep a short domain vocabulary in CONTEXT.md (or the current upstream convention, GLOSSARY.md). Record consequential design choices as ADRs. The agent can then use the same terms in discussions, tickets, code, and reviews.

For a change whose shape is uncertain, use /grill-with-docs to work through the decisions and write them down. Run /to-spec once the conversation has enough detail. Break the spec into small, ordered tickets with /to-issues in older installations or /to-tickets in the current upstream skills. Then use /implement against those tickets.

The sequence is:

shared vocabulary + ADRs → grill → spec → tickets → implement → review

You can enter the sequence at whichever step the work needs. A small, well-specified fix may already have a ticket. An uncertain feature should be grilled before an agent starts writing code.

Put tickets where the project works

The tracker is an adapter for the process. One project keeps issues in a local docs/TODO.txt; others use Vikunja or Taiga. What matters is that the agent knows where the authoritative spec and tickets live, how to record blockers, and how to update their status. Write those rules into the repository’s agent documentation. A tracker integration skill can handle the API details without changing the development sequence.

This also makes the setup portable. Moving to a new project means teaching the agent that project’s domain, tracker, and checks, rather than rebuilding the workflow.

Make implementation answer to the spec

Implementation includes tests and a diff review. Review the result against two different questions: does the code follow the project’s standards, and does it actually satisfy the originating spec? The latter catches plausible code that solves the wrong problem. A previous review found duplicate-write paths after a large test suite passed because it checked a safety claim against the call path.

Where the project’s rules allow it, use a different model family for review. A typical split is Claude writing the code and GPT reviewing it, since a different family brings different blind spots. Claude reviewing Claude has also proven decent, so one family is still a workable setup when you can only use one provider. For larger changes, a multi-review skill can run distinct axes such as correctness, quality, tests and performance, security, and, for frontend, accessibility. Give each reviewer the same bounded diff and the actual spec; collect actionable findings back into the tracker.

Attach stack-specific skills where they help. Go work can load guidance for concurrency, error handling, testing, and security. iOS work can use Swift and mobile guidance. For exposed web APIs, mobile clients, or MCP tools, apply relevant OWASP-based web, mobile, and LLM security skills during implementation and review. A checklist gives the agent concrete questions to ask; it does not turn a code review into a security certification.

Start with one change: write down the vocabulary and decision, turn the request into a spec and tickets, implement one ticket, and review the diff against the spec and its security boundaries. Adjust the tracker, skills, and review axes to fit the next project.

Inherited agent notes can send the next agent down the same dead end

Fri, 09 Oct 2026 00:00:00 +0000

A new agent can go through a failed investigation again if its first job is to absorb the conclusions of the previous agent. In the course of an authorised security exercise the user was repeatedly asking for a clean start as the prior progress files could be somewhat misleading. The useful reset was to establish a small verified baseline before using the inherited notes to select the next experiment.

A hint survived longer than its evidence

The conversation history had instructions to go it alone after a number of failed attempts at the task. Another handoff stated the prior agent had got lost and that its notes could be misleading to the replacement.

One concrete example concerned an environment hint favoring IPv6. A later SUMMARY.md excerpt said:

IPv4 and IPv6 behave identically everywhere tested

It was very explicit that the IPv6 hint in AGENTS.md didn’t apply in that case. That’s a useful clarification, with a caveat: this is a recorded summary of the checks, not an independent re-run of every network probe. It does support the removal of that hint for that particular surface. It doesn’t in any way establish equivalence for all services or a successful resolution of the problem. The outcome is still unknown.

Rebuild only enough context to choose a test

On a restart read the current task and the mandatory operating instructions. Observe the authorization boundaries and safety rules. Be very clear in your mind about the difference between the instructions and the factual observations about the environment. A line in AGENTS.md could be a binding rule, it could be a fact about the setup or it could be a hypothesis that you need to go out and check.

Then establish the facts required to inform the next decision. In a network investigation that might involve confirming the target endpoint, checking that it’s reachable and then making a baseline request to it. In a code issue scenario you’d want to reproduce the failure that was reported and then have a look at the current code before accepting any diagnosis from a previous developer.

Only then do you compare the inherited notes against that baseline. That way you don’t re-run the whole investigation and the new agent has its own baseline to work from.

A handoff instruction can be as short as:

Establish a minimal baseline from the current tool output.
Treat inherited diagnoses as hypotheses.
For each claim you make, you need to be able to locate the evidence or at the very least be able to run a very cheap check.
Keep the required operating and safety instructions in force.

Preserve the test behind a negative result

A note such as “IPv6 works better” is completely devoid of the endpoint, the request and the comparison that would actually make it useful. “No difference on these tested endpoints” is much more specific and much easier to verify.

For future handoffs, record:

The claim and its scope (including when it was checked).
The command or test and a pointer to its output.
What remains is an interpretation or an unproven lead.

Keep the failed attempts too and state what each one ruled out. A failed request with one set of credentials doesn’t rule out the whole protocol. The next agent needs to be able to make the judgement as to whether repeating that test would in fact add any evidence.

Copying an assertion into successive summaries doesn’t constitute independent corroboration. If the raw output is missing then unverified is the correct designation rather than promoting it to a fact.

Prior to your next agent handoff, pick the assumption that will drive the next action and attach the relevant tool output in support of that assumption. If you can’t find it then that will be the restart task.