Write the supported spec

Reproducing the uppercase-channel failure is not yet an implementation contract. The Builder needs a precise boundary it can test.

{
  "problemStatement": "Provider lookup rejects uppercase channel configuration.",
  "acceptanceCriteria": [
    "SLACK selects the Slack provider",
    "Existing lowercase callers keep working"
  ]
}

A supported specification describes observable behavior and the evidence behind it. It does not prescribe a favorite helper name before reading the code.

Give the Builder a Supported Spec

Extend the Investigator to return an evidence-backed specification with behavioral acceptance criteria.

Hands-on Exercise 3.2

Open agent/subagents/investigator/agent.ts. Add these properties to outputSchema.properties:

agent/subagents/investigator/agent.ts

affectedFiles: { items: { type: "string" }, type: "array" },
approach: { type: "string" },
problemStatement: { type: "string" },
risks: { items: { type: "string" }, type: "array" },
acceptanceCriteria: {
  items: { type: "string" },
  minItems: 1,
  type: "array",
},
testStrategy: { type: "string" },

Add all six names to required. An empty risk array is valid, but the Investigator must make that assessment explicitly.

Update agent/subagents/investigator/instructions.md with an inspection procedure:

agent/subagents/investigator/instructions.md

Start with the package scripts and exported entry point, then read the nearest implementation and tests connected to the reproduced behavior. Keep the affected file list narrow.
 
Write acceptance criteria as observable behavior. Name the exact test command and the new or existing case that will prove each criterion. Record compatibility risks separately from the implementation approach.

This procedure keeps exploration tied to the claim. Broad repository exploration increases context use and encourages unrelated changes.

For the public API case, require the Investigator to inspect the exported Notification contract and existing callers. Its specification should describe backward compatibility before a person sees the approval request.

Try It

Run the authored checks:

pnpm typecheck
pnpm exec eve info

Invoke the uppercase-channel issue again:

pnpm exec eve invoke "$(cat fixtures/issues/bug-example.md)"

Inspect the structured result and ask:

Does every affected file connect to the reproduced behavior?
Can each acceptance criterion pass or fail without reading the approach?
Does the test strategy name a real repository command?
Are compatibility risks explicit?

The result should remain useful if a different Builder implements it tomorrow.

Swap the implementation

Imagine the Builder normalizes the channel at a different layer. If the acceptance criteria still make sense, they describe behavior. If they fail because a helper has the wrong name, the spec has become a code recipe.

The affected list contains the repository

Require each path to connect to the reproduced behavior. Broad scope gives the Builder permission the investigation did not earn.

The test strategy says run tests

Name the command and the case it must cover. “Run tests” is not a reproducible test strategy.

Commit

git add agent/subagents/investigator
git commit -m "feat(factory): write supported specifications"

Done-When

The problem statement matches the reproduced behavior
Affected files remain connected to the claim
Acceptance criteria describe observable behavior
The test strategy names real commands and cases
Public API specifications include compatibility risks

The Builder now has a specification supported by repository evidence. Some investigations should never produce one.

Solution

The complete property definitions and required-field list appear in the exercise. Compare agent/subagents/investigator/agent.ts with the solution branch if structured output rejects the result.