| name | graph-backlog-generation |
| description | Human-in-the-loop PLANNING skill — investigates the project (graph + git + harness/gaps) and runs the whole ANALYZE→DESIGN→PLAN chain in one faceted loop to produce a COMPLETE PRD injected as graph backlog (epics, tasks, testable AC) for a separate agent to implement. Applies the project's planning methodologies — Impact Mapping + OKR per epic, JTBD, MoSCoW, WSJF/Cost-of-Delay, User Story Mapping, Example Mapping (Rules/Examples → Given-When-Then AC), SPIDR splitting, INVEST, Definition of Ready, Risk Matrix; the full catalogue lives in the skill body. Stops for the human after each complete PRD and iterates the next cycle from the project's own findings (dogfood). Does NOT implement. Triggers — graph-backlog-generation, gerar backlog, criar PRD, planejar feature, detalhar épico, novo ciclo, "plan the next thing", "what should we build next". |
| triggers | ["graph-backlog-generation","gerar-backlog","criar-prd"] |
| version | 2.4.0 |
| author | Diego Nogueira |
| date | "2026-07-03T00:00:00.000Z" |
| tools_used | ["deliver","generate-prd","import-prd","brainstorm","node add","edge add","decompose","gaps","gate","phase","query","search","insights","harness"] |
| tokens | ~1000 |
graph-backlog-generation
The planner. One faceted, human-in-the-loop chain that turns a vague idea (or the
project's own findings) into a complete PRD injected as graph backlog — epics,
tasks, and testable AC — so a separate agent (graph-builder-leafcutter) only
implements. Plans only; never writes production code.
⛔ Hard rule — PLAN ONLY, zero code (read this first)
When this skill is invoked you cannot write code. Not a stub, not a test, not a
one-line edit, not "just to verify a shape". The only artifacts you produce are
Jurisprudência desta etapa (casos reais + o blind-spot que os produziu): references/field-lessons.md → seção "⛔ Hard rule — PLAN ONLY, zero code (read this first)". Carregue sob demanda.
The planner also never touches git: no commit, no new/switched branch. The
backlog lives in the shared, gitignored workflow-graph/graph.db — it persists across
branches, so stay where you are. Branch-per-implementation is the builder's job.
When to Use
- Start of any cycle: a vague idea, a new feature, or "what should we build next?"
- Backlog is empty / stale, or a cycle just shipped (iterate the next from findings)
- You have a PRD to import and structure into the graph
- You explicitly want planning/PRD/AC work — NOT implementation (that's the builder)
Do NOT use when an unblocked task already exists and you just need to code → use
graph-builder-leafcutter.
Deterministic plan (low-reasoning fast-path)
If you are a low-reasoning model (Haiku, DeepSeek Flash, MiniMax, etc.), follow THIS —
the framework names used later (Cynefin, WSJF, MoSCoW, INVEST…) are expanded here as
plain rules, so you never need to know them. PLAN ONLY: emit graph nodes + text,
never code/git. Top to bottom, obey every STOP/DEFAULT.
-
agf preflight "<theme>" → verdict wip-conflict/duplicate-risk on another
epic → STOP, report (someone already owns it). Else continue.
-
agf exec chain "stats --select data.byStatus; gaps --severity required" (1 round-trip,
sem shell &&) → is there already ready backlog? Yes → STOP: tell the user to run
graph-builder-leafcutter.
-
Frame in one line each (no jargon): WHO needs it · WHAT changes for them ·
WHY (one measurable win). Uncertainty rule: you can see how to build it → write
tasks now; you cannot → add ONE risk node spike: investigate <X> and stop on that area.
-
agf generate-prd "<idea>" (or agf import-prd <file>).
-
Per epic: agf node add --type epic … with Objective + 1 measurable Key Result
in the description (a number/percent/latency — not "improve X").
-
agf decompose. Slice outside-in from the surface the user operates (web → the
frontend screen; agf → the CLI command; API → the endpoint). Every leaf ≤2h and
self-sufficient:
- each leaf = ONE control on that surface proven end-to-end (button/field/screen),
not a backend layer — e.g. "the Run button on the rules screen returns true/false",
not "build the rule engine"
- backend/data work is only a leaf wired
depends_on a surface AC that fails without
it — pull it, never plan it top-down
- title
IMPLEMENT:|WIRE:|FIX:|DOCS: <one outcome>
- description: the WHY + exact file paths to touch (
src/…) + "do not recreate"
- 2–4
--ac lines, each Given-When-Then with a concrete number/boolean/string,
observable at the surface (números batem / estado renderizado / true|false)
- the exact test file
src/tests/<stem>.test.ts
-
Priority tag — use this table, no judgement:
| situation | tag |
|---|
| breaks/blocks others without it | must |
| clear value, not blocking | should |
| nice-to-have | could |
Order within must: blocks-most-others first; tie → smallest job.
-
agf gaps --severity required --json → for each gap run its applyVia → repeat until
ready: true.
-
agf check <each task id> → AC score <60 → rewrite the AC concretely (add the missing
number/fixture), retry.
-
Completeness critic — NOT optional. Run a COMMAND for each, never just think. A
finding with no tool output behind it is invented — discard it. A "no" becomes a node:
- a. Write the flow
A → B → C → …. Does every arrow have an owning epic? (An
arrow with no owner is a missing epic — that is how a backlog looks complete and isn't.)
- b.
node show each contract → can each consumer do its job with ONLY those fields?
(A target/id/budget nobody carries is the classic hole; no gate sees it.)
- c. For each promise in a milestone/KR → which task produces it? (grep it.)
- d.
ls the module you're extending → which files did you never open? grep -rn
each exported symbol → any with no caller that you're about to duplicate?
- e. Query the graph per axis: security · credentials · wall-clock timeout · logging ·
concurrency · reproducibility. Owned, or deferred with a node?
- f. Could a KR go green without the value? (Then the KR is the defect.)
- g. What is the laziest wrong implementation that still passes? (→ AC or
risk.)
Includes: does any metric prove its own instrument is plugged in?
-
STOP for the human: "backlog ready, N tasks, critic swept with evidence (findings: …)
— run graph-builder-leafcutter."
Never: write/edit code, create/switch a git branch or commit, or inject a task whose
AC has no concrete, checkable value.
Golden Rules (planner edition)
The full universal set lives in _shared.md → Golden Rules (universal
engineering) — obey it verbatim; the list below is the planner-specific slice.
Each planning handoff MUST follow _shared.md → Close-out Report Format
(what was injected + proof + Próximo: X — porque [fundamento]).
The project's golden rules, distilled for ANALYZE/DESIGN/PLAN. Non-negotiable:
- Investigate first, never duplicate.
agf preflight "<theme>" + scan existing
epics + a repomix code-map BEFORE planning. A wip-conflict / duplicate-risk
verdict = STOP; another agent or a shipped epic already owns it.
- Expand, never recreate (DRY) — and point at the WIRED module, not a legacy
twin. search/query/grep/repomix for the owning module and plan to extend it.
Net-new only when it provably does not exist — the strongest epics wire dormant/
partial code that already lives in the repo. Trap: two files can share the same
stem (a legacy
core/llm/tier-router.ts beside the live model-hub/tier-router.ts);
a task whose EXPAND-pointer names the dead twin makes the builder edit the wrong
file. Before you write a file path into a task, grep -rn its consumers and name
the one that is actually imported by the live path — code wins the plan.
- Graph is the source of truth. No task without a node; code/graph beat
memory/plan (counts in memories go stale — reconcile with
agf stats/query).
- Dogfood. Drive the whole cycle with
agf itself; in-repo use npm run dev -- <cmd>, never the stale installed binary.
- Distill to atomic. Every leaf ≤2h, INVEST-Small, GWT-testable AC; one
responsibility per node; decompose oversize into subtasks; WIP=1 (pull, don't push).
- Quality as AC, not prose. Clean Code · SOLID · KISS · YAGNI encoded as testable
constraints (file <800, fn <50, 1 responsibility, immutability, no
any, typed errors).
- Plan only. Never implement/test/review here — hand the backlog to the builder.
Mandatory Flow
This chain is a Generator–Critic (Reflection) loop, not a straight line: the injection
half generates, Step 5.5 attacks it with tools, findings become nodes, repeat until the
critic comes back empty with evidence.
┌──────────────────────── GENERATOR ────────────────────────┐
[investigate graph + git + code → find WHITE SPACE] → (checkpoint human on direction)
→ generate-prd / import-prd → decompose → node add + edge add (epics·tasks·AC)
→ gaps (close required) → validate AC (agf check) → verify tree
└───────────────────────────┬───────────────────────────────┘
▼
COMPLETENESS CRITIC (Step 5.5 — 7 tool-grounded sweeps)
findings → nodes ──┐
▲ │ (loop until empty, with evidence)
└───┘
▼
STOP for human ⇆ next cycle
The critic is mandatory and self-triggered. A human asking "did anything get left out?"
means the loop never closed — that pass must run before they ever see the backlog.
The chain ends by stopping for the human with a complete PRD in the graph. It
never enters IMPLEMENT — it hands the backlog to the builder.
Workflow
Detailed methodology playbooks live in references/methodologies.md
(Impact Mapping + OKR-outcome per epic · 5W2H · JTBD · Cynefin · Pareto ·
MoSCoW · WSJF/Cost-of-Delay · Lean/Toyota · JIT · Decomposition & distillation
(epic→task→subtask) · User Story Mapping / walking-skeleton slicing · Repomix
codebase analysis · Example Mapping (Rules/Examples/Questions) · SPIDR
splitting · INVEST · GWT · Three Amigos · Definition of Ready · TDD-as-AC ·
SOLID · KISS · YAGNI · DRY/Rule-of-Three · Law of Demeter · Composition · SoC · Clean
Code · Documentation/ADR · Logging & Observability · Risk Matrix · PERT · Six Sigma ·
STRIDE/OWASP). Load it on demand.
Command-agnostic: the commands below are illustrative. The source of truth for
the exact, current command is always agf retrieve-command "<intent>" (RAG-IN) or
agf help — so this skill never goes stale when commands are added or renamed.
Step 1 — Investigate & find white space (dogfood)
Read the project's real state across three surfaces, not just the graph:
Surface A — the graph & process state:
agf preflight "<theme>"
agf stats · agf insights bottlenecks · agf harness --violations · agf gaps --severity required
agf query --type epic --status backlog
Surface B — the codebase, via Repomix (deterministic, ~0 LLM tokens to produce).
The point is to understand the project without reading all of it — extract signal,
then drill into the one area that matters. The 3 cheap passes:
repomix --no-files --token-count-tree 200
repomix --compress --remove-comments --stdout --include "src/**"
repomix --include-diffs --include-logs --stdout
Read the map for strong vs weak areas: weak = oversized files (>800 lines),
git-churn hotspots (default sort is most-changed-first = bug-prone), missing
tests/error-paths in the compressed structure; dormant = exported-but-unwired symbols
(best EXPAND targets); strong = small + low-churn + tested → leave alone (Lean). Secret
scan is on by default; never use --no-security-check.
Full repomix catalog (scope/git/output-shaping/remote/MCP grep_repomix_output):
references/repomix-investigation.md. Always
repomix --help for the live flags. Repomix is an optional external tool — where
it is not installed, fall back to Surface A (agf graph-map) + agf search / grep -rn
over src; the investigation still completes, just less compressed.
The deliverable of this step is white space: value that is real, grounded in
findings, and NOT already covered by an existing epic or in-flight by another epic.
A backlog of 1000+ nodes is normal — the planner's hardest job is not adding
duplicates. Prefer wiring dormant/partial code over net-new (golden rule); the
strongest epics come from code that existed but was unwired.
Jurisprudência desta etapa (casos reais + o blind-spot que os produziu): references/field-lessons.md → seção "Step 1 — Investigate & find white space (dogfood)". Carregue sob demanda.
agf query --type task --status blocked --select 'data[].{id,description}'
Group what you find by finding-shape, not by reading each node cold:
- Half an epic (mechanism ready, no consumer built) → usually a real, scopeable
epic on its own: decompose the missing consumer as tasks with AC.
- Systemic scaffolded family (N files, same shape, one root cause) → one
epic/decision covering all N, never N separate tasks — the builder already named
the whole family in one of the blocked nodes; don't re-derive it file by file.
- Overlaps an already-wired system → usually NOT an epic; either retire the
dormant module (a
task to delete it) or scope a narrow task for just the
non-overlapping differentiator the finding already named.
- Superseded by a sibling → usually a cleanup task (retire the loser), not a
feature epic — verify the finding's claim (
agf harness --dormant) before trusting
it blind, since a stale finding may have been fixed since.
A blocked node with no finding text (just the harvest boilerplate, never triaged) is
still raw signal — treat it like an untriaged repomix hotspot, not pre-digested.
Step 2 — Frame the problem & confirm direction
Apply 5W2H + JTBD to state the problem; Cynefin to size uncertainty; Pareto to pick
the 20% scope that delivers 80% value. Impact Mapping anchors it on the goal:
Goal (Why, measurable) → Actors (Who) → Impacts (How behavior changes) → Deliverables (What) — each candidate epic must trace back to one goal through an impact, and each
epic carries an OKR-style measurable outcome (Objective + ≥1 Key Result) so it
ships outcome, not just output. Order the Pareto-selected Must/Should set by WSJF
(Cost of Delay ÷ Job Size) to sequence biggest-value-soonest. See references.
Jurisprudência desta etapa (casos reais + o blind-spot que os produziu): references/field-lessons.md → seção "Step 2 — Frame the problem & confirm direction". Carregue sob demanda.
Step 3 — Generate / import the PRD
agf generate-prd "<idea>"
agf import-prd <file> [--build-tree]
PRD covers: vision · problem · objectives · architecture · functional reqs ·
NFRs (perf/security/a11y as measurable AC) · risk matrix.
Organize epics along a User Story Map backbone (journey steps left→right) and
commit only the walking-skeleton / MVP release slice this cycle — the thinnest
end-to-end runnable path (Pareto + JIT). Deeper stories stay as deferred
should/could epics for the next cycle to pull without re-planning.
Slice CONSUMER-SURFACE-FIRST (outside-in) — the DEFAULT decomposition axis
agf is a factory that generates N different apps depending on what the dev drives it
toward. Whatever the app, the backbone starts where the user actually operates the
product, and every slice must PROVE itself there. The surface differs per app; the axis
is the same:
| app kind | consumer surface = where you slice first |
|---|
| web / admin | the screen + its controls (a route, its buttons/fields/tables) — the primary case |
| CLI (agf itself) | the command (agf <cmd> output) |
| API / service | the endpoint (request → response) |
Por que outside-in vence (Walking Skeleton de Cockburn, GOOS, OKR, estigmergia/ACO, Little's Law): references/field-lessons.md → "Fundações do outside-in". A regra está acima; a fundamentação é consulta.
How it lands in the graph:
- Each leaf = ONE control on the surface, proven end-to-end. Not "build the rules
service" but "the Run button on the rules screen evaluates and renders true/false" — the
whole vertical (control → API → domain logic → store → rendered result) for that one
control, wired and clicking.
- Backend/data work is PULLED, never pushed. Do NOT plan a backend epic top-down. A
backend task exists only as a leaf wired
depends_on a surface AC that fails without
it — the failing surface operation is what justifies the descent. Every inner node stays
traceable to a control the user can see.
- The epic's Key Result is the surface operating whole, observable at the surface: "the
batch screen processes a real batch — the totals reconcile, eligible vs non-eligible each
carry a reason, and export/upload/bulk-insert are all wired and clickable" — a number + a
boolean + a rendered state, never "it works". A control on the screen with no leaf that
proves it = incomplete epic (the arrow/seam sweep, applied to UI controls).
- Order: a screen's controls become sibling leaves; a control another depends on (create
the record before you run it) gets a
depends_on edge. Screens order left→right along
the journey — unless a screen must exist first because others read what it configures
(a rules screen sits above the flow that consumes those rules).
Step 4 — Structure as graph + decompose to atomic tasks
agf node add --type epic|requirement · agf edge add <from> <to> --type <rel>
agf decompose
Each task gets MoSCoW priority + INVEST-scored, Given-When-Then testable AC
(multiple discrete --ac entries — never one prose blob). Derive the AC by Example
Mapping: list the story's Rules → one concrete Example per rule becomes one
GWT --ac (with its fixture); open Questions become risk nodes, never
silent gaps. A rule with no example is untestable — don't inject it. Split oversized
stories with SPIDR (Spike · Paths · Interfaces · Data · Rules) alongside the
distillation heuristics. TDD/SOLID/security expressed as AC, not prose.
The task-node contract (what makes a leaf buildable)
Every leaf the builder pulls must be self-sufficient — if it would have to
re-investigate the codebase to start, the node isn't done. Epic nodes carry the
Objective + Key Result (the success metric) in their description/AC; leaves carry:
- Title — imperative verb prefix signalling work type:
WIRE: IMPLEMENT:
RELEASE: FIX: DOCS:. One atomic outcome (≤2h).
- Description — the why + exact EXPAND pointers: the real file paths and symbols
the executor must touch in your repository, and an explicit "do not recreate".
Trap: spell each path out — never a brace-glob shorthand. Writing
src/cli/commands/{init,start,doctor}-cmd.ts in a description trips the
phantom_pointer gap: the detector reads the whole glob as ONE nonexistent file and
flags the node (and misleads the builder into hunting a path that isn't there). List
the three real paths separately (…/init-cmd.ts, …/start-cmd.ts, …/doctor-cmd.ts).
- AC — 2–4 discrete
--ac Given-When-Then criteria, each independently testable
with a concrete fixture (new Database(':memory:'), stub-LLM token counter). Make
them observable: a number, a boolean, a status code, an exact string. Weak
phrasing with no threshold trips has_testable_ac — put the concrete value in the AC.
- Contract pointer — name the boundary's
contract node (see enrichment layer) so
the leaf carries the exact shape, not a vague "returns JSON".
- Test file — the exact
src/tests/<stem>.test.ts path + the fixture to use, so the
builder writes the RED test without re-deriving it.
- Tags — MoSCoW (
must|should|could) + theme; tags become ACO trails for the builder.
- Edges —
depends_on to any sibling that must land first (encodes build order).
Backlog enrichment layer (what a light model needs to ship effortlessly)
A buildable epic is more than tasks + AC. Inject the supporting nodes a junior/light
model would otherwise have to infer — each with the right type and edge
semantics. This is the difference between "a list of tasks" and "implementable with
zero re-investigation":
| Node type | Carries | Wire with |
|---|
contract / interface | the exact request/return shape + the source of each field (which existing helper to reuse, with file:line) | task implements → contract; consumer consumes → contract |
risk | the failure mode + its mitigation phrased as the AC that absorbs it | risk related_to the task(s) it threatens |
constraint | global guardrails — zero-deps, file <800, fn <50, no any, layer boundary, read-only | parent_of the epic |
requirement / NFR | perf · security · a11y as measurable criteria | a task must implements it (see the trap in Step 5) |
performance_budget | a concrete budget (e.g. fluid ≤300 nodes, poll ≤2s) | related_to the affected task |
The contract node is the highest-leverage artifact — for every API/module boundary,
give the exact TS shape and where each value comes from (summarizeLedger(...).totals
at file:line), so a cheap model fills the body without exploring. Every Example-Map
Question/risk becomes a node, never a silent gap; the mitigation you write on
the risk reappears as a concrete AC on the owning task (traceable via related_to).
Spec-driven layer (opt-in, raises rigor without code)
Maximise agf's planning surface — all still PLAN-only, zero code:
agf constitution
agf preset --apply <name>
agf spec --generate <template>
agf spec-sync link <specId> <nodeId>
Encode the non-negotiables (immutability, no any, layer boundaries) once in the
agf constitution instead of repeating them per task — gates validate against it. For a
high-stakes epic, generate a phase spec and spec-sync link it to the node so spec and
graph never drift. agf preset sets the cycle's workflow rigor up front.
Step 5 — Close gaps & validate
agf gaps --severity required
agf check <taskId>
agf gate <phase>
Jurisprudência desta etapa (casos reais + o blind-spot que os produziu): references/field-lessons.md → seção "Step 5 — Close gaps & validate". Carregue sob demanda.
On the same fresh backlog, consumer_proof and no_unresolved_blockers also fail by
construction — nothing is built and the deps don't exist yet. Read the DoD's own
ac_quality_pass line (it prints the score against its minimum) as the planner's real
signal; the aggregate ready:false is about the builder's future, not your tree.
Completeness-Critic gate (MANDATORY — run it yourself, never wait to be asked)
This gate is the Reflection / Generator-Critic pattern (a.k.a. CRITIC) made
mandatory: the same failure mode — a backlog that looks done and isn't — is what
Reflection exists to kill, by separating generation from evaluation. You already
played the generator (injected the epics/tasks). Now switch roles and become an
adversarial critic whose only job is to prove the backlog INCOMPLETE. This is a
distinct pass in the same loop — a change of posture and a fresh evaluation against
rigid criteria, not a spawned sub-agent (no fan-out; golden rule 13). Run it as a
tight cycle: Generate → Critique → Revise → re-Critique until the critic returns
zero open holes; only then stop for the human.
The critic's stance is assume-incomplete-until-proven. Do not ask "is this done?"
(the generator always answers yes). Ask "what is MISSING that would block a builder?"
and force yourself to emit the list explicitly — every missing risk, dependency,
seam, driver, or surface — before concluding, reasoning end-to-end (chain-of-thought
over the value flow, not a glance at the node count). An empty critic list is only
credible after the six lenses below have each been answered out loud; "I looked and it's
fine" is the generator talking, not the critic.
The DoD sweep proves the nodes that EXIST are well-formed. It says nothing about the
nodes that SHOULD exist and don't. That is the hole a human keeps catching by feel —
and "the human noticed" is not a process (golden rule 8: the trigger must be the
method, not someone remembering). So before you stop for the human, run these six
lenses over the whole injected backlog yourself, out loud in the close-out. Each is a
question that has caught a real missing node; a "no" answer is a node to add (or a
risk to park). Report the sweep result — Completeness sweep: 6 lenses, N holes found + closed — so the human never has to ask "algo mais?".
- Value-chain walk — arrows AND seams. Write the theme's end-to-end flow as an
explicit chain and name the owner of every arrow (a stage) and every seam
(the data contract crossing between two stages). Unowned arrow → missing task;
unowned seam → missing
contract node. (The "WALK IT" guidance in Step 3 is this
lens for arrows; the seam half is just as load-bearing — two epics can each be
complete while nobody owns the record-shape that passes between them.)
Aggregator-without-producer — the seam's most expensive shape. When the theme is
"prove/aggregate/score X" (a verdict fusing N signals into one confidence), the
generator blind-spot is shipping the READER of each signal but not its PRODUCER. It
looks complete because on the happy path the signals are green — but the signal that
is usually EMPTY (a consumer-proof, an outcome, an attestation nobody records) has no
task that FILLS it, so the verdict is structurally stuck at its incomplete band and
the "means" are never legible. For every pillar an aggregation epic reads, name the
task that PRODUCES it (grep the writer); a pillar with a reader and no producer is an
unowned seam. And when the theme is "make the means explicit," the contract must carry
a per-signal rationale/why field — otherwise the explain surface invents it.
- Set-coverage. Any gate/router/activation keyed on evidence must produce evidence
for every unit it can act on, not just the flagship (see the measure→activate
anti-pattern). Measure 1 of N → the gate defaults 1 of N.
- Consumer-surface matrix. For every "prove value" claim, is it proven in each
surface the project ships — CLI · web/dashboard · CI-gate? A value proven only in the
CLI leaves the web (and the gate) consumer blind; that is a missing
COBRAR(<surface>)
task, one per surface the theme touches.
- Claim-staleness / reconciliation. Does any change flip a claim asserted
elsewhere — generated docs (CLAUDE.md/AGENTS.md), memory, a CI baseline, a default
flag? Every flipped claim needs a reconciliation owner (a
DOCS: or rebaseline task).
A default that changes from OFF→ON silently turns three things stale: the doc that
says "OFF", the regression baseline that priced "OFF", and the memory that recorded it.
- Foundational-driver exists? Any task that assumes a harness / suite / fixture /
runner — verify that thing exists in the repo (
ls/grep), don't assume. A gate
that references a suite dir that was never created, or a measurement that "runs via" a
driver nobody built, is a missing foundational task the rest silently depends on.
- Latent-inventory triple. Enumerate every latent capability the theme names, then
check each has all three: measured ∧ wired ∧ charged. A capability with a
wire but no measurement (or a measurement but no consumer-surface charge) is still
value leaking — the theme is "activate the latent", so partial coverage is the defect.
Direction of travel (make it deterministic). Lenses 3–5 are mechanical enough to
become agf gaps detectors (consumer-surface coverage, claim-staleness, missing-driver)
— the same medir→wirar→cobrar the project preaches, applied to the planner's OWN
completeness so the tool fires the check instead of the human's feel. Until then, the
six-lens sweep is a MANDATORY manual gate, reported every cycle.
Jurisprudência desta etapa (casos reais + o blind-spot que os produziu): references/field-lessons.md → seção "Completeness-Critic gate (MANDATORY — run it yourself, never wait to be asked)". Carregue sob demanda.
Step 5.5 — Completeness critic (MANDATORY, tool-grounded — never hand over an uncriticised backlog)
This step is the Critic half of a Generator–Critic (Reflection) loop: Steps 1–5 generate,
this step attacks what they produced, findings become nodes, repeat. It is not optional and
never human-triggered. If someone has to ask "did anything get left out?", the skill already
failed — their intuition is not a control. gaps, DoR and check score the nodes that
exist; nothing scores the node you never wrote. This is that missing scorer.
Jurisprudência desta etapa (casos reais + o blind-spot que os produziu): references/field-lessons.md → seção "Step 5.5 — Completeness critic (MANDATORY, tool-grounded — never hand over an uncriticised backlog)". Carregue sob demanda.
So: a sweep is not a thought, it is a command. Each finding below must name the tool
output that produced it — a grep hit, a file you opened, a node show, a graph query. A
finding with no external evidence is hallucinated critique and must be discarded, not
injected. A sweep that "looks fine on reflection" was not run. This is the same principle as
golden rule 8 (enforcement = deterministic trigger, not an agent remembering), applied to
critique itself: the critic must be grounded in something outside the model.
Run all seven before Step 6, every cycle, and report the result — including "swept,
nothing found". Each sweep pairs a question with the tool that answers it:
| # | Sweep | The question | Grounded by |
|---|
| 1 | Arrows, not boxes | Write the flow A → B → C. Does every arrow have an owning epic? | graph query per stage; an arrow with no owner = missing epic |
| 2 | Contract sufficiency | For each contract, can each consumer do its job with ONLY those fields? | node show the contract; list consumers; a field everyone needs and nobody carries (target, id, budget) is invisible to every gate |
| 3 | Promise ownership | For each claim in a milestone/KR: which task produces it? | grep the milestone text; search tasks per promise. A promise with no producer is the thing you'd report as delivered |
| 4 | Modality not run | Which files of the module you extend did you never open? Any exported-but-uncalled symbol you're about to duplicate? | ls the module, grep -rn each symbol's callers. Unread file = unverified DRY claim |
| 5 | NFR axes | Owned or consciously deferred with a node: security · credentials · wall-clock timeout · logging · concurrency · reproducibility? | graph query per axis. "Nobody thought about it" is not deferral |
| 6 | Goodhart | Could a KR go green without delivering the value? | read each KR against a plausible trivial implementation — the outcome-level twin of a weak AC |
| 7 | Failure-mode inversion | What is the laziest wrong implementation that still passes? | read each AC set adversarially → the answer is a missing AC or a risk |
Sweep 7 has a special case worth naming: instruments lie by omission. A ledger reports
cost == 0 just as happily when nobody wired the counter as when nothing was spent. Any KR
measured by your own instrument needs an AC proving the instrument moves (inject a fake
cost → the counter must rise). Otherwise the metric proves only that it is unplugged.
Sweep 5's blind-spot, earned the hard way: a read-only happy path hides who owns the write.
When an epic explores, crawls, or drives a system it did not author, the generator plans the
reading and never plans the acting — because every example it imagined was a read. Nothing in
the tree is malformed; the gates go green; and the first real run mutates or destroys state
nobody authorized. Worse, any epic that persists what worked (a pheromone map, a cached
skill, a learned path) turns one successful destructive action into a reinforced one, repeated
every run after. So: for any epic that acts on a system it does not own, ask who classifies the
action before it executes, and make the unclassified case BLOCK rather than proceed —
a permissive default on an unrecognized action is the failure mode, not the recognized
destructive one. Pair it with sweep 5's other half: grep the graph's existing constraint
nodes against your NEW tasks. A task that casually proposes a third-party library or a new
surface can contradict a global constraint that has been in the graph for cycles; the constraint
is invisible to the task's own gates, so only the critic catches it.
Sweep 7's twin, earned the hard way: evidence lies by provenance. An oracle that keys on
absence of evidence (data is None → inconclusive) is structurally blind to evidence from
the wrong source — which is the likelier failure. The generator blind-spot: a target contract
that carries WHERE to go (url) but makes proving-you-arrived optional (ready_probe: Probe|None)
looks complete, because on the happy path you always land on the right page. Then reality
redirects — an auth wall, a consent gate, an error page, a stale SPA route — and the wrong page
loads perfectly: HTTP 200, a valid read, a plausible number (usually 0). That number becomes a
false fail (the system never broke; the test never arrived), or a false pass when the KR
happens to expect 0. Every gate stays green because every node is well-formed. So: any node
that reads a value from somewhere must carry the provenance of that read, and identity of the
source is asserted BEFORE the value is compared. When you write a contract with an optional
validate/identity field, ask what loads successfully when you're in the wrong place.
Findings are not prose — each becomes a node (task · contract update · risk · ADR) or an
explicitly recorded deferral. Then re-run gaps and re-sweep. Report every finding to the
human with its evidence, so the critique is auditable rather than trusted.
Step 6 — Stop for the human ⇆ iterate (the loop)
When the PRD is complete and DoR passes, STOP and present it for the Three Amigos
sign-off — the human (Product + Test) may interrupt, adjust scope, or approve. On
approval, the next cycle re-enters Step 1, seeded by the freshly-updated project
findings (continuous dogfood evolution).
Jurisprudência desta etapa (casos reais + o blind-spot que os produziu): references/field-lessons.md → seção "Step 6 — Stop for the human ⇆ iterate (the loop)". Carregue sob demanda.
Anti-Patterns
- Do NOT write code, tests, or stubs, and do NOT touch git (no commit, no new/switched
branch) — the deliverable is graph nodes; implementation + branch-per-feature is the
builder's. If you opened an editor, you left the planner — revert and node-ify it.
- Do NOT hand over a backlog whose completeness critic (Step 5.5) never ran. If the human has
to ask "did anything get left out?", the skill failed. Report the sweep every cycle — even
when it finds nothing.
- Do NOT critique by introspection — "let me re-read my plan and see if it's complete" is
intrinsic self-correction, which measurably makes output WORSE (Huang et al. 2023);
every sweep must cite a tool result (grep/file/graph), per CRITIC (Gou et al. 2023).
- Do NOT mistake green gates for completeness.
gaps, DoR and check score the nodes that
EXIST; none can see the epic you never wrote. A fully green tree with a missing stage is
the normal way this fails.
- Do NOT chase global
agf gaps debt — filter to your own node ids; only your subtree
must be required-clean
- Do NOT add a
requirement/NFR/contract node without wiring a task that implements
it — that creates a phantom required gap
- Do NOT
node rm + re-add just to fix AC — node update --ac "<c1>" "<c2>" … REPLACES
the whole ac[] in place (repeatable; pass every criterion you want to keep) and
preserves all edges; enrich prose via --description
- Do NOT implement, test, or review here — that is
graph-builder-leafcutter
- Do NOT emit one run-on AC — use multiple discrete, testable Given-When-Then criteria
- Do NOT skip the investigate step — the backlog must be grounded in real findings
- Do NOT over-produce (Lean): plan only the Pareto-justified scope per cycle. When the
backlog is already saturated, scan existing epics first (
agf query --type epic --status backlog) and EXPAND/wire dormant code rather than recreate — confirm
white space with the human before injecting overlapping epics
- Do NOT hardcode a gate phase or flag that may not exist — verify with
--help first
- Do NOT treat a failing
status_flow_valid on fresh backlog as a defect — it is
expected; the planner bar is AC-present + AC-score ≥ 60
- Do NOT ship an epic with tasks but no measurable outcome/KR — that is output blind to
outcome; give every epic an Objective + Key Result
- Do NOT plan a backend/data epic top-down. Slice outside-in from the consumer surface
(screen/command/endpoint the user operates); a backend leaf exists only wired
depends_on a surface AC that fails without it — pull it, never push it. A backend
node with no surface control tracing back to it is speculative work (Walking Skeleton /
GOOS outside-in TDD) and inflates time-to-market for zero observable value
- Do NOT frame a KR as an inner artifact ("the service exists", "the parser is done"). The
KR is the surface operating whole, observed in the consumer's mode — a number, a
boolean, a rendered state (
_shared.md Golden Rule 16). A control on the screen with no
leaf that proves it end-to-end = incomplete epic
- Do NOT let a measure→activate pair measure only the flagship unit. When an epic
gates activation on evidence (smart-defaults, auto-tuning, a router that flips a
behaviour per item), the paired measurement task must produce evidence for every
unit the gate can flip — not just the one you started with. Measure 1 of N and the
gate can only ever default that 1; the other N−1 stay dark. Budget one measurement
leaf covering the whole activatable set (or a loop over it), wired
depends_on before
the gate.
- Do NOT call a story "ready" with rules but no examples, or with unresolved Example-Map
questions — convert each to a
risk node or send it back to DESIGN
Graph mechanics (CLI contract)
- Parent/child:
agf node add --parent <id> sets parentId directly (one call) —
no separate containment edge needed. agf query --parent <id> does not reliably
list children; verify structure via each child's parentId (from agf node show).
- AC at creation: pass repeatable
--ac "<Given… When… Then…>". import-prd and
generate-prd extract AC from the PRD markdown and synthesize testable Given-When-Then
criteria for tasks that lack them — the output envelope includes data.acCoverage with
per-task coverage. Use node add --ac to add or refine ACs after import.
- Dependencies:
agf edge add <from> <to> --type depends_on to enforce build order
inside an epic (e.g. release-task depends_on the wiring-task).
edge add is POSITIONAL: agf edge add <from> <to> --type <rel> — there is no
--from/--to (passing them silently no-ops). Relations you'll use: depends_on,
parent_of, implements (task→requirement/contract), consumes (consumer→contract),
related_to (risk/perf→task). Confirm the live set with agf edge add --help.- AC is revisable in place (NOT write-once).
node update --ac "<c1>" "<c2>" … is
repeatable and REPLACES the node's whole ac[] — it does not append, so to
revise AC pass the COMPLETE set (the criteria you keep + the new ones). Edges are
preserved — never node rm + re-add just to fix AC (that needlessly re-wires every
edge; earned the hard way — a 5-task epic was rebuilt before this flag was noticed).
node update --description edits the prose independently.
- Status is forward-only — planner never sets
in_progress. Leave tasks in
backlog (or ready once DoR passes). in_progress/done are the builder pulling.
If a node slipped to in_progress, valid transitions are done|blocked|ready|
quarantined — you cannot go back to backlog; set it ready.
Token Economy
Output is auto-compressed with --ai; no manual flags needed. Levers:
--select <path> — shape every read down to the field you need (output→input lean).agf retrieve-command "<intent>" (RAG-IN) — the exact current command, no guessing.agf montar-output "<objetivo>" (RAG-OUT) — reuse PRD scaffolds instead of re-drafting.agf savings / agf metrics — the ledger logs token economy automatically.
See _shared.md for the full arsenal.
Pilot Protocol
Planning chain is human-in-the-loop, not autonomous. The build/execute loop
(next→brief→submit) lives in graph-builder-leafcutter. See _pilot-protocol.md.
Related
graph-builder-leafcutter — consumes this backlog and implements it autonomously (ACO + GA-inspired learning loop).
