The PR

How a spec page becomes a pull request, and the body Wolf writes.

The PR

Wolf ships the requirement as a diff, not the implementation. The spec PR is the request, a tracking issue is the ledger, the implementation PR is the answer.

   wiki spec page (source of truth, never edited to match reality)
        │  Wolf copies, does not rewrite
        ▼
   PR #1  "spec: <title>"          diff = docs/specs/<slug>.md
        │  reviewable, merges, creates a durable in-repo anchor
        ▼
   tracking issue  "<slug>: implement"    ◀── acceptance criteria live here
        │  built by whoever has repo access
        ▼
   PR #2  "feat: <title>"          diff = actual code
        │  closes the tracking issue, links back to PR #1
        ▼
   Wolf copies PR/CI/evidence URLs onto the wiki spec page

Wolf does not scaffold. Writing stub files, imports or symbol names into a repo it has never seen is guessing, and a wrong guess costs the reviewer more than it saves. Whether the target repo accepts a docs/specs/ directory is unresolved.

The body answers four questions

  "what am I being asked to do?"      -> Ask
  "how do I know when I'm done?"      -> Acceptance criteria (Given/When/Then)
  "what am I NOT allowed to change?"  -> Out of scope + Non-negotiables
  "who decides / where do I reply?"   -> Tracking + Open questions

Wolf cannot read the target repo’s PR template, CODEOWNERS or branch protection. So the body is self-contained and survives being appended to an unknown template. Anything repo-specific goes in as a <placeholder> — never an invention.

Open questions in the body are not a loophole: they must be answerable by engineering unilaterally, inside the PR. A question that needs a product answer means the spec was never ready.

Acceptance criteria

Given = the initial context. When = an event or action. Then = an observable outcome (Gherkin).

• One AC = one observable outcome. If it needs “and also”, split it.
• An AC that cannot fail is not an AC. “The code is clean” is not an AC.
• No AC may name a file, function or class unless the spec is creating it.
• If the spec cannot produce 3 falsifiable ACs, the spec is not ready to be a PR.

The template

<!-- Opened by Wolf from the Belief Engines wiki. Wolf has no read access to this repo. -->

## Ask

<One sentence, imperative. "Add per-tenant rate limiting to the public API.">

Spec (source of truth): https://internal.beliefengines.io/<area>/<slug>
Spec revision: `<git sha of the wiki page at time of opening>`
Wiki page owner: @<person>

## Why now

<2-4 sentences. The forcing function, not the feature description.>

## Acceptance criteria

Each item is independently checkable by someone who has never read the spec.
Tick the box, then replace `<evidence>` with a link to the CI run or the test name.

- [ ] **AC-1** — Given <initial context>, When <action>, Then <observable outcome>.
      Evidence: `<evidence>`
- [ ] **AC-2** — Given …, When …, Then …
      Evidence: `<evidence>`
- [ ] **AC-3** — Given …, When …, Then …
      Evidence: `<evidence>`

## Out of scope

- <thing a reasonable reviewer would assume is included, and is not>
- <thing deliberately deferred, with the reason>

## Non-negotiables

<Constraints that are the spec, not implementation taste. Latency budgets, data
boundaries, auth model. If the build cannot meet one, that is a conversation, not a
silent substitution.>

## Left to engineering

<Everything else. Say it explicitly: file layout, libraries, schema shape, naming.
The wiki owns WHAT. This repo owns HOW.>

## Open questions for engineering

Answerable here, by you, without asking product.

- [ ] <question Wolf cannot answer because it cannot see the code>

## Tracking

- Tracking issue: #<n>
- Implementation PR: <filled in when opened>
- Wiki status: `requested` -> updated by Wolf on merge