---
title: The PR
description: "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.

```text
   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](/be-agent-wolf/open-questions).

## The body answers four questions

```text
  "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](https://cucumber.io/docs/gherkin/reference/)).

- 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

```markdown
<!-- 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
```