cache-product-endpoint

move-office

• write the goal verbatim in the plan header as

  Goal:

  ;
• set

  Spec: none — the contract is this plan

  ;
• omit

  Covers:

  from every task.

Done when

PLAN.md

SPEC.md

spec-from-scratch

TOO FINE                          RIGHT
- Open the config file            - Add Redis connection settings to the
- Add a redis section               application config, reading host and
- Save the file                     port from environment variables

- Search for papers               - Identify the three most-cited papers on
- Open each result                  retrieval-augmented generation published
- Note the citation counts          since 2023, with citation counts

TOO COARSE                        RIGHT
- Implement caching               - Add a cache abstraction with get/set/invalidate
                                  - Wire the product endpoint through the cache
                                  - Add invalidation on product update

• If a task cannot fail in an interesting way, it is too fine — merge it.
• If a task has more than one postcondition, it is too coarse — split it.
• A task must carry enough context to stand alone, because it may be handed to a separate agent or person.

Done when:  the product endpoint returns a cached response on the second
            identical request within the TTL window
Verify by:  run the integration test ProductCacheTests

Done when:  every interviewee has confirmed the scheduled slot in writing
Verify by:  each of the six invitations shows an accepted response

• Done when

  describes state, never activity. Not "the cache code is written" — that is activity. "A repeated request is served from cache" is state.

• Verify by

  names something that produces evidence: a command, a test, a file check, an API response, a document, a direct observation.
• When no automatic check exists, write

  Verify by: user confirmation

  . That is valid evidence once the user actually confirms — weaker than a machine check, and the report will label it

  attested

  rather than measured. A postcondition merely awaiting confirmation is not yet satisfied.
• A task with no possible postcondition is not a task. It is either a detail of another task or it does not belong in the plan.

PLAN.md

1. Read the SPEC in full, or capture the user's goal verbatim.
2. Observe the current state (step 1 above).
3. Decompose into tasks (steps 2–4).
4. Run the plan quality gate.
5. Write

   PLAN.md

   at version 1.

• What was actually done, according to the ledger?
• Did it succeed? How do you know from the current observable state — not from the executor's claim?
• What did execution discover that the previous plan could not have known?

1. Identify which remaining tasks are now possible, and which have become impossible.
2. Make remaining tasks specific using information now observable. This is the main job: a task that said "contact the site owner" becomes "email Alice Nguyen, the listed maintainer".
3. Remove tasks that are no longer needed.
4. Add tasks the current state revealed as necessary.
5. Fix errors and assumptions in the previous plan.
6. Adapt when an expected element, file, result, person, or capability was not found.

• Plan only future work. Completed tasks leave the plan; the ledger holds them. Do not renumber survivors.
• No attempted task survives. Any task with a

  partial

  ,

  blocked

  , or

  failed

  ledger entry is finished as an instruction: whatever remains of it becomes a new task with a new ID. Reusing the ID would make the executor re-run side effects that already happened — and because the executor never redispatches a task that has a ledger entry, a reused ID would simply never run again. Say in the new task's reasoning which prior task it continues.
• Carry discovered facts forward into the plan text. The plan is the working memory of the run. If execution learned that the top contributor is Alice, later tasks say "Alice", not "the top contributor". This is why the loop needs no separate memory mechanism.
• Increment

  Plan version

  and fill

  Replanned because

  with the concrete trigger.
• If nothing material changed, say so and leave the plan untouched.

Replanning changes the strategy. It never changes the definition of success.

• which acceptance criterion cannot be met as written;
• what execution discovered that makes it unreachable;
• the options — change the contract, change the approach, or accept partial completion.

Done when