Activity

1. gilesknap commented on May 4, 2026

   

   gilesknap

   on May 4, 2026

   ContributorAuthor

   More actions

   under development at:
   gilesknap#6

   with some minor underlying template changes here:
   gilesknap#5
2. gilesknap

   self-assigned this

   on May 4, 2026
3. gilesknap commented on May 4, 2026

   

   gilesknap

   on May 4, 2026

   ContributorAuthor

   More actions

   Also consider some recommendations for .Claude/settings.json. Some already go in the repo but some should probably just be recommend for the global settings e.g. https://engineeratheart.medium.com/the-9-claude-code-settings-power-users-change-on-day-one-acbb0c161823
4. gilesknap commented on May 4, 2026

   

   gilesknap

   on May 4, 2026

   ContributorAuthor

   More actions

   I'd also like to consider helping Claude with code search. This sounds almost too good to be true but worth a look https://medium.com/vibe-coding/claude-code-is-wasting-98-of-your-tokens-on-search-heres-the-fix-1034b2039291
5. gilesknap commented on May 5, 2026

   

   gilesknap

   on May 5, 2026

   Last edited by gilesknap

   ContributorAuthor

   More actions

   I'm trying the Pocock workflow and early impressions are very good.

   @coretl @hyperrealist @vredchenko @garethnisbet you may be interested? Here is a summary of what I'm using (a prototype for what will go in the main docs of this repo):

   Matt Pocock's Agentic Engineering Workflow

   A reference for the design → spec → slice → implement pipeline used with Claude
   Code in this repo. The four stages each have a slash-command or skill installed
   under ~/.claude/. Each stage starts from a clean context window so the agent
   isn't dragging stale assumptions into the next phase.

   One-line summary

   GitHub issue
      │
      ▼
   [/grill-me]   interview the human until the design is pinned down
      │
      ▼
   [/to-prd]     synthesise the design as a PRD issue
      │
      ▼
   [/to-issues]  break the PRD into independently-grabbable issues
      │
      ▼
   [tdd skill]   implement each issue, one red→green→refactor cycle at a time
   

   Between every stage: /clear. The next stage reads from the artefact written
   by the previous stage (the issue body), not from the conversation history.

   ---

   Stage 1 — /grill-me

   Purpose. Walk the design tree branch-by-branch with the human, asking one
   question at a time. The agent recommends an answer for each question and
   explains its reasoning so the human can redirect rather than rubber-stamp.

   When to use. You have a problem statement (typically a GitHub issue) but
   no concrete design. Decisions are interlinked and you want to surface them
   deliberately rather than discover them mid-implementation.

   Inputs.

   • A reference to the problem space: an issue number, an idea, a reproduction.

   Outputs.

   • A shared understanding between human and agent of every meaningful design
     decision. Lives only in the conversation.

   Discipline.

   • The agent asks one question at a time and waits for an answer.
   • The agent grounds its recommendations in code references (file paths, line
     numbers, existing class names) rather than hand-waving.
   • The agent explores the codebase to answer questions that the codebase can
     answer, instead of asking the human.
   • When agreement is reached on a sub-decision the agent moves on; it doesn't
     re-litigate.

   Typical exit signal. The agent has nothing more to ask, or the human says
   "looks good — write it up."

   ---

   Stage 2 — /to-prd

   Purpose. Convert the conversation context from /grill-me into a Product
   Requirements Document and post it as a new issue on the project's tracker.

   When to use. Immediately after /grill-me while the design context is
   still in the agent's memory.

   Inputs.

   • The current conversation context (no arguments needed for the simple case).
   • Optionally an issue number for the original problem to cross-link.

   Outputs.

   • A new GitHub issue containing the PRD, formatted with these sections:
     • Problem Statement (in the user's voice)
     • Solution (in the user's voice)
     • User Stories (a long, numbered list)
     • Implementation Decisions (architectural and interface choices, no code)
     • Testing Decisions (what to test, prior art, what makes a good test)
     • Out of Scope
     • Further Notes
   • Triage label applied so it enters the team's normal triage flow.

   Discipline.

   • The agent does not re-interview. It synthesises from what it already knows.
   • The agent first sketches the major modules it expects to build/modify and
     confirms with the human. It calls out candidates for "deep modules"
     (narrow public interfaces hiding meaningful complexity) and asks which to
     cover with unit tests.
   • The PRD avoids file paths and code snippets — both go stale fast.
   • The agent posts the issue at the end so the artefact is durable; if the
     agent's GitHub token can't post, it provides the body for the human.

   Typical exit signal. The PRD URL is shared. The conversation can be
   cleared.

   ---

   Stage 3 — /to-issues

   Purpose. Break a PRD into a set of independently-grabbable GitHub issues
   using vertical-slice tracer bullets. Each issue cuts thinly through every
   layer (schema, API, UI, tests) and is demoable on its own.

   When to use. After a PRD exists. Run this in a fresh context window — the
   skill reads the PRD from the issue tracker, not from conversation history.

   Inputs.

   • An issue reference (number, URL, or path) for the PRD.

   Outputs.

   • A set of GitHub issues, each tagged HITL (needs human in the loop, e.g. for
     a design decision or a review) or AFK (away from keyboard — implementable
     end-to-end without further input).
   • Dependency relationships between issues recorded in the descriptions.

   Discipline.

   • Vertical slices, not horizontal. Don't ship "all the schema" or "all the
     tests" as one issue — ship "user can do thing X end-to-end" as one issue.
   • Prefer many thin slices over few thick ones.
   • Prefer AFK over HITL where possible.
   • The agent presents the proposed breakdown as a numbered list and quizzes
     the human on granularity, ordering, and HITL/AFK tagging before posting.

   Caveat for refactor work. Some PRDs (large refactors with type-contract
   entanglement) don't slice into many independent issues. In that case the
   output may be just 2–3 issues: small AFK prep issues plus one large HITL
   issue for the atomic switch. That's still the correct answer — the
   constraint is on the work, not the workflow.

   Typical exit signal. Issues are posted, dependencies are clear, the human
   picks the first one to implement.

   ---

   Stage 4 — tdd skill

   Purpose. Implement one issue using a strict red → green → refactor loop,
   producing tests that describe behaviour through public interfaces rather
   than implementation details.

   When to use. After /to-issues has produced an issue you want to land.
   Run in a fresh context window per issue.

   Inputs.

   • The issue to implement (reference, or paste in the body).

   Outputs.

   • A PR (or commit series) that ships the issue green, with tests that
     describe externally-observable behaviour.

   Discipline.

   • Vertical slices, not horizontal. Write one test → make it pass → write
     the next test. Do not write all tests first; that produces tests of
     imagined behaviour rather than real behaviour.
   • Test through public interfaces. A good test would survive a complete
     refactor of the internals. If renaming a private function breaks a test,
     that test was wrong.
   • Minimal code per cycle. Add only enough to pass the current test. No
     speculative features.
   • Never refactor while red. Get to green first; refactor with the safety
     net of green tests.
   • Use the project's vocabulary. Test names and interface names match the
     domain glossary documented in CONTEXT.md / docs/explanations/ / ADRs.
     Respect the architectural decisions already made.

   Per-cycle checklist:

   • The test describes behaviour, not implementation.
   • The test uses the public interface only.
   • The test would survive an internal refactor.
   • The code is minimal for this test.
   • No speculative features added.

   Typical exit signal. All planned tests are green. PR opened.

   ---

   Why /clear between stages

   Each stage produces a durable artefact (a GitHub issue, a PR). The next
   stage reads from that artefact, not from conversation memory. Clearing
   between stages:

   • Keeps the agent's context window focused on the current task.
   • Stops stale assumptions from one stage leaking into the next.
   • Forces the artefacts to be self-contained — if a future maintainer (or a
     fresh agent) can't pick up the work from the artefact alone, the artefact
     is incomplete and should be improved.
   • Makes the agent's context cost roughly proportional to the size of the
     current task, not the full history of the project.

   Skip /clear only when staying within one stage (e.g. iterating on the
   to-issues breakdown before posting).

   ---

   Other useful commands in the same family

   These don't sit on the main pipeline but compose well with it:

   • /zoom-out — ask the agent to step back and explain a section of code
     at a higher level. Useful when grilling is going too narrow too fast.
   • improve-codebase-architecture — find deepening opportunities in
     existing code. Reads CONTEXT.md and ADRs and proposes specific refactors.
     A maintenance counterpart to the design pipeline.
   • grill-with-docs — variant of /grill-me that updates CONTEXT.md
     and ADRs as a side effect, keeping the project's design documentation in
     sync with decisions made during interviews.
   • diagnose — a disciplined bug/perf-regression loop (reproduce →
     minimise → hypothesise → instrument → fix → regression-test). Use instead
     of /grill-me when the entry point is a defect, not a feature.
   • triage — process incoming issues through a state machine of triage
     roles. Use on the receiving end of /to-prd and /to-issues to keep the
     tracker tidy.
   • setup-matt-pocock-skills — scaffold per-repo config (issue tracker,
     triage label vocabulary, domain doc layout) that the other skills read.
     Run once per new repo.

   ---

   Worked example (from fastcs work so far)

   Issue #120 ("Allow a single FastCS server to have multiple top level
   Controllers with different prefixes") had several months of inconclusive
   discussion in comments. The pipeline turned that into actionable work:

   1. /grill-me #120 — 17 design questions answered one at a time. Mid-way
      the human realised dict-keyed-by-id was cleaner than list-with-id field
      and posted a heads-up comment to the original issue thread. Final summary
      covered runtime model, lifecycle, transport contract, EPICS internals, GUI
      layout, scope cut, demo design, and tests strategy.
   2. /clear.
   3. /to-prd — produced PRD chore(deps): update github actions #351 with 34 user stories, full
      implementation and testing decisions, and explicit out-of-scope items.
      Posted to the tracker tagged enhancement, python, needs design.
   4. /clear.
   5. /to-issues 351 — broke the PRD into a small number of issues (two[/-]
      [+]6. /to-issues 351 — broke the PRD into a small number of issues (two AFK prep issues plus one HITL atomic-switch issue, given the[/+][-] AFK prep issues plus one HITL atomic-switch issue, given the[/-]
      type-contract entanglement of the refactor).
   6. /clear before each.
   7. tdd skill per issue — implement each one red → green → refactor.

   The above process created this PR