ef-perspective-discovery

Files (1)

• SKILL.md

SKILL.md (first lines)

# Perspective discovery — Stage 3 of 5

Turn a feature specified **somewhere else** into closed decisions and a written contract for **this**
repository, before any code exists.

The deliverable is a list of contradictions, a set of closed decisions, and the contract. It is not
a plan document, and it is not code.

## Where this sits

This is **not** the first stage. The feature was already defined at product altitude and written up
by Stage 2; the docs folder you were handed is that output.

```
Stage 1 /ef:grilling  →  Stage 2 /ef:feature-docs  →  grill-decisions · RFC · PRD · INDEX
        ↓
THIS SKILL, once per target repo  →  closed decisions → the contract
        ↓
Stage 4 /ef:implement  →  Stage 5 /ef:audit  →  the handoff doc
```

Three consequences:

- **The docs are upstream intent, not repo truth.** They were written at product altitude, often
  before the code existed, usually by a session that could not see this repository. That is
  precisely why Step 1 exists.
- **One product grill fans out to N repos.** Each target repo runs this skill independently and
  reaches its own decisions against the same doc set. That is what "perspective" means here.
- **A `FICTION` verdict can reopen a product decision, not just a local one.** When a false claim is
  load-bearing for an RFC decision, escalate it up a stage and amend the RFC. Do not quietly route
  around it in this repo — the sibling repos are reading the same false claim and will not know.

## Why this exists

Feature docs are prose. Prose cannot be compiled, so it rots the moment it is written and nothing
catches it. A docs folder that reads beautifully routinely contains load-bearing claims about code
that are simply false — a job that does not exist, a migration that was never created, a permission
gate that is enforced nowhere, a table shape someone refused. Reading the docs harder never finds
those. Checking them against the code does.

So: **this is contradiction-hunting, not reading.**

---

## Step 1 — Anchor check (always first)

Extract every concrete claim about code from the docs: `path:line` references, file names, symbol
names, table and column names, migration names, "we already have X" assertions.

Verify each against this repository. Classify:

| Verdict | Meaning |
|---|---|
| `VERIFIED` | Exists, and says what the docs claim |
| `MOVED` | Exists elsewhere or at a different line — record the real location |
| `CHANGED` | Exists at that location but behaves differently than claimed |
| `FICTION` | Does not exist at all |
| `N/A` | Belongs to another repository — do not guess, mark and move on |

Report a table plus a count per verdict. **Any `FICTION` or `CHANGED` on a load-bearing claim means
the docs cannot be trusted as written**, and every decision resting on that claim is reopened. Say so
explicitly, and amend the RFC where the claim was load-bearing for a decision.

**Check each failure against the decisions' `Would reopen if` conditions** in `grill-decisions`. That
field exists so this step is a match rather than a judgement call: a false claim that satisfies a
stated reopen condition reopens that decision by its own terms, and one that satisfies none is a
correction to the docs rather than a reversal. Without the match, every false claim triggers the same
undifferentiated alarm and the one that matters gets lost among them.

Cheap, mechanical, and it prevents the tax where a wrong spec is discovered one amendment at a time
during implementation. `/ef:spec-drift` runs this step alone.

---

## Step 2 — Scout fan-out

Read-only subagents in parallel, one per **area of this repo the feature touches**.

### First: is a fan-out warranted?

**Can you name the files this feature changes, before starting?**

- **Yes** → skip the fan-out. Step 1's anchor check plus a direct read of those files is enough, and
  four scouts would return what you already know. Say you skipped it and why.
- **No** → fan out. Not knowing which files change is precisely the condition scouts exist for.

Step 1 is never skipped at any scale: it is minutes of work and it is the only thing that catches a
doc claiming something false. The fan-out is the expensive half, and it is the conditional one.

### Picking the axes

One scout per layer or subsystem, derived from the docs' own anchors plus this repo's structure —
read the repo's context file, its guides, and its directory layout to find the real seams. Not one
per file, not one per requirement.

Axes must be **disjoint**: two scouts reading the same code is wasted budget and produces conflicting
maps. 4 is the floor for a real feature; past ~8 the reports blur together and you stop reading them
properly.

Typical seams, whatever the stack: the aggregate being extended and its children · the
transaction/consistency mechanism · the propagation or eventing mechanism · the thing you are
extending rather than creating · schema and generated code · background work and side effects ·
auth, permissions and identity plumbing · test conventions · validation and any legacy to delete ·
the presentation layer's routing, state, components and i18n conventions.

Always include a **conventions** scout: how does this repo wire a new unit of this kind, what is the
newest example to copy, and what are its gate commands? That scout's output is not disposable — it
becomes the bindings half of the contract, and Stage 4 codes against it.

### Assign each scout a lens

The area says what to read; the **lens** says how. Parallel readers given the same method produce
correlated reports however different their areas, and the fan-out buys nothing. Assign one lens per
scout from the `ef-shared` skill's `references/lenses.md` — evidence-audit, assumption-surfacing, pre-mortem, red-team, or
second-order — matched to what that area is most likely to hide.

The lens is also what generates that scout's pre-registered questions. Apply the method; never name
it in the report.

From micaelcf/ef-harness, MIT.

More from micaelcf/ef-harness