---
name: project-decision-policy
description: Use at the start of any task to choose the right workflow, and before any non-trivial decision to apply the configured autonomy tier and the decision-quality bar. The router and autonomy authority for all other PRD Plugin skills; resolves "which skill, and may I decide this myself?".
---

# Project Decision Policy

This skill is the router and the autonomy authority for the PRD Plugin method.
Every other skill defers to it for two questions: **which workflow applies**, and
**how much autonomy do I have for this decision**. It reads
`automation.autonomy_level` from `.prd_plugin/config.json`.

## Iron Law

```text
MATCH THE STOP THRESHOLD TO THE CONFIGURED AUTONOMY TIER; NEVER UNLOCK THE FLOOR.
```

Raising the autonomy tier moves *where* you stop to ask. It never lowers the
quality bar and never unlocks the hard floor below (secrets, force-push, another
repository, irreversible outward spend). Shipping the work — push / merge /
publish — is not on that hard floor; the tier governs it (Part 3).

## Part 1: Router — which skill when

Pick the entry skill from the situation. Do not start a heavy planning chain for
a small change, and do not skip planning for genuinely new scope.

| Situation | Start with |
| --- | --- |
| New/unclear idea, no source records yet | `project-brainstorm` |
| New feature/scope that needs PRD → architecture → plan | `project-planning-lifecycle` |
| Mid-development: user adds/changes/removes/defers a feature, requirement, or UI element while artifacts already exist ("what if we add X", "make this work differently", "drop this", "park this") | `project-change-request` |
| Small, well-understood bug or change | `project-request-intake` → `project-systematic-debugging` → `project-test-driven-implementation` → `project-git-workflow` (NOT planning-lifecycle) |
| Outside agent/user proposes a change or reports a bug | `project-request-intake` |
| Implementing an already-accepted `REQ-*`/`IMP-TASK-*` | `project-test-driven-implementation` |
| Investigating a failure before any fix | `project-systematic-debugging` (a **loop** with a breaker: three consecutive finds means stop fixing and re-ground) |
| Folding a cross-cutting change into this repo's truth | `project-local-integration` (downstream) / `project-fold-it-in` (hub only) |
| About to claim work done/fixed/passing | `project-verification-before-completion` |
| Recording a durable decision | `project-decision-ledger` |
| Capturing or querying durable domain/codebase knowledge (ingest on close; query before re-deriving) | `project-llm-wiki` |
| Stuck on something you cannot resolve yourself | `project-blocker-resolution` |
| End of a work session | `project-session-close` |
| Planning/running/resuming/auditing bounded lifecycle mechanics | `project-deterministic-workflows` first, then the domain skill for any judgment |

If two skills seem to apply, use the more specific one; if a workflow hands off
("then use X"), follow the handoff.

**Admin slash commands** (Claude Code) sit alongside the skills:
`/prd-status`, `/prd-track`, `/prd-graph`, `/prd-autonomy`, `/prd-hooks`,
`/prd-config`, `/prd-drift`, `/prd-version`, `/prd-new`, `/prd-reflections`,
`/prd-workflow`, `/prd-close`, and `/prd-report`. Use the named command instead
of reconstructing its bounded operation from prose.

**MCP state tools** (when `.mcp.json` wires the `prd-plugin` server) are the
preferred way to read/write `.prd_plugin` state. Use `prd_find` for bounded
discovery and `prd_get` for one full record; use `prd_create`, `prd_update`, and
`prd_link` for ordinary TRK/REQ/HLT state instead of hand-editing JSON. Keep the
specialised goal, evidence, decision, change, and validation tools for their
guarded workflows. `prd_next_id` is only for embedded planning IDs inside
canonical artifacts; record-backed IDs are allocated inside create operations.
Subagents are off by default. Do not use them unless the user explicitly asks
and current host/runtime permissions allow them. If either condition is absent,
do not use subagents. If both are present, read and follow
`.prd_plugin/method/subagents.md` before creating any worker.

**Deterministic workflow authority.** Before asking the model to sequence,
bookkeep, validate, allocate, collect facts, choose tests, or perform lifecycle
mechanics, inspect `prd_workflow_list` and `prd_workflow_plan`. Run the matching
workflow with a stable idempotency key. If it pauses at `waiting_judgment`, the
model receives only the hash-bound source bundle and returns only the declared
schema; deterministic resume validates it. Domain skills govern the quality of
that judgment, while the engine governs all mechanical execution and state.

At task/session entry, plan and run `session.start` when enabled; its config,
state, and status preflight is the deterministic basis for selecting the domain
skill.

**Unified configuration.** Discover effective settings with `prd_config_get`
and `prd_config_list`; mutate only with `prd_config_set`, `prd_config_profile`,
or the equivalent `prd_config.py` operation. Use `/prd-config` for operator
configuration. Reflection bank CRUD uses `prd_reflection_create`,
`prd_reflection_update`, and `prd_reflection_delete`; use `/prd-reflections`
instead of hand-editing `RFQ-*` arrays.

**Read-only UTCP surface.** When the host mounts the manual produced by
`prd_tools.py`, use its read-only UTCP status, tracking, decisions, evidence,
wiki, drift, gate, reporting, Substrate, config-inventory, and workflow actions
for bounded observation. Treat it as an observe/recall path: mutate only through MCP
or validated CLI authorities.

**AI-Collab Substrate adapter.** Read `integrations.substrate` before assuming
the adapter is active. `off` is inert, `observe` permits only canonical record,
graph, and event projection, and `coordinate` permits only capabilities that are
also explicitly listed. AI-Collab owns runtime execution; project-truth writes
must still use the validated PRD MCP tools. Direct config JSON is the stored
representation, not the preferred write path; `prd_config.py` and the MCP
configuration tools are the validated authorities.

**Knowledge/tool-first self-service.** Before raw code or git search, use this
order: **Capability discovery** for available host/plugin/MCP/UTCP/workflow and
Substrate tools; **Substrate memory** and repository recall when connected; the
**LLM wiki**; then canonical PRD records through validated tools. **Raw
repository search** is the fallback for exact implementation facts,
verification, stale knowledge, or gaps those structured sources did not answer.
Unavailable or disabled Substrate capabilities are not blockers—verify the
handshake/config, then continue down the ordered fallback.

## Part 2: Autonomy tiers

`automation.autonomy_level` selects how much the agent decides versus asks. The
tier moves the threshold for the *discretionary middle* **and for shipping the
work** (push / merge / publish); only the hard floor (Part 3) is constant in
every tier.

| Tier | Decide yourself | Stop and ask for |
| --- | --- | --- |
| `autonomous` | everything in the discretionary middle, **plus shipping the work — commit, push, merge to the work's own `main`, tag, and publish to the repos and registries it is for** (gate must be green first) | the hard floor only (secrets, force-push/history destruction, another repository, irreversible outward spend) |
| `key_decision` (default) | routine, reversible, low-impact work | key decisions even when confident: architecture/design choices, scope changes, anything irreversible; **explicit consent before push / merge to `main` / publish**; high severity/risk, or ambiguous-with-high-impact — plus the hard floor |
| `guided` | only the unambiguous, trivial, or read-only | most non-trivial decisions — propose and confirm; **explicit consent before push / merge / publish** — plus the hard floor |

A decision's place in the middle is set by two axes: **reversibility** (blast
radius if wrong) and **confidence** (is there a clear path). Higher reversibility
and confidence → decide; lower → ask, at the threshold the tier sets.

**Continuing the planned work is not a decision.** Finishing a step and moving to
the next planned step is the work, not something to ask permission for. Do not end
a completed step with "shall I proceed?" / "which would you prefer?". Ask only when
the *next* action hits the floor (Part 3) or the configured tier requires a check
for that specific action. In `autonomous` that means: complete the work and report
it; stop only for the floor. Offering a pause is fine as a one-line P.S., never as
a blocking question. How you report results is governed by
`.prd_plugin/method/reporting.md` (plain language first; never lead with ID codes).

### Changing the tier

- **Persistent:** set `automation.autonomy_level` in `.prd_plugin/config.json` to
  `autonomous`, `key_decision`, or `guided`. The one-line way (no manual JSON
  edit):

  ```bash
  python scripts/prd_gate.py set-autonomy autonomous   # or key_decision | guided
  python scripts/prd_gate.py set-autonomy              # show the current level
  ```

  (downstream: `python .prd_plugin/scripts/prd_gate.py set-autonomy <level>`).
  When the user asks to change the mode, make this change and record it as a
  `user_requested` decision.
- **Per session:** if the user says "continue autonomously" / "finish this
  yourself", treat the current task as `autonomous` without editing config. The
  floor still holds.

### Switching the plugin off

`/prd-off` applies the `off` configuration profile: every automatic behavior
(hooks, stop guard, commit gate, workflows, telemetry) stops; skills and tools
stay installed but only act when explicitly invoked. `/prd-on
[lean|balanced|full]` restores a working profile (default balanced).

### The continue guard in `key_decision` (REQ-150)

`key_decision` means **stop for key decisions** — it never meant *ask permission
to keep working*. The Stop guard used to ignore this tier entirely, so an agent
could stop every few minutes to ask things the method, the plan, or the repo
already answers.

While an open `TRK-*` goal exists, the guard now **blocks an undeclared stop**
in `key_decision` too and tells you to resolve the question yourself first
(capability discovery, the wiki, canonical state, then the code — see
`.prd_plugin/method/self-service.md`).

You still stop for what the tier is *for*, using one escape: write the actual
question into `.prd_plugin/local/autonomy-pause` and stop. The guard lets that
through. Legitimate reasons are a genuine key decision (architecture or scope
choice, anything irreversible, high severity/risk) and the consent floor
(push / merge to `main` / publish, secrets, another repository).

It needs an open goal to have anything to continue toward, the per-session
continue cap still bounds it, and `automation.key_decision_continue_guard:
false` switches it off. `guided` is untouched — it always allows a stop.

### Run-until-done in `autonomous` (Stop guard)

In `autonomous`, a deterministic Stop hook (`prd_stop_guard.py`) keeps you working
toward the **active goal** — an open `TRK-*` record of `type: goal` (or
`active_work`) — instead of stopping for pointless checkpoints. It blocks the stop
while such a goal is open, no pause is requested, and the per-session continue cap
(`automation.autonomous_continue_cap`) is not hit. So in this tier:

- **Open a goal at task start.** Create a `TRK-*` record with `type: goal`,
  `status: active`, and a one-line summary of what "done" means (use
  `/prd-track` or `project-memory`). The guard has nothing to work toward until
  this exists — without it, autonomous mode just stops normally.
- **Don't stop to ask "shall I proceed?"** — you'll just be told to continue.
- **Finish the goal:** close it by marking its `TRK-*` record `complete` (after
  `project-verification-before-completion`), then the guard lets the session stop.
- **To stop for the floor:** when you genuinely need the user (the floor below) or
  hit a real blocker, create `.prd_plugin/local/autonomy-pause` with a one-line
  reason (and file the blocker via `project-blocker-resolution`). The guard then
  allows the stop and clears the marker. This is how a legitimate stop is told
  apart from a pointless one.

**Multi-session safety:** the guard binds to ONE session. The same explicit-user
and host/runtime permission gate applies. Authorized child sessions set
`PRD_STOP_GUARD=off` (or `PRD_WORKER_SESSION=1`); all other worker rules live in
`.prd_plugin/method/subagents.md`.

Disable the behavior with `automation.autonomous_run_until_done: false`, by
leaving `autonomous` tier, or with `/prd-hooks disable`.

### Run-until-done

In `autonomous`, the Stop guard enforces run-until-done: while an open TRK
goal is a valid candidate, the session continues instead of stopping at
checkpoints. Candidates are bounded four ways: worker sessions opt out
(`PRD_STOP_GUARD=off`), only the goal-owning session is blocked, goals owned
by another host runtime are excluded, and goals not updated within
`automation.stop_guard_goal_max_age_days` (default 2) never conscript a
session that does not own them — run-until-done continues your current work,
it does not adopt stale goals. Pause legitimately with
`.prd_plugin/local/autonomy-pause`.

## Part 3: The floor

Two different things get called "the floor". Keep them apart — conflating them is
what makes `autonomous` mode stop at the exact step that ships the work.

### Shipping the work — governed by the tier, not a blocker

Committing, pushing, merging to the work's own `main`, tagging, and publishing the
package this sanctioned work produces to its configured remote/registry are the
*completion* of the work, not a floor violation.

- In `autonomous`, **the tier is your standing consent**: finish and ship
  end-to-end, then report (record `decided_by: autonomous`). The one precondition
  is that the full gate is green — never ship red.
- In `key_decision` / `guided`, stop and get **explicit consent** before you push,
  merge to `main`, or publish. (Local commits on a work branch never need consent
  in any tier — see `project-git-workflow` → Commit Discipline.)

### The hard floor — never unlocks, in ANY tier including `autonomous`

Always stop for human authority for anything in `project-blocker-resolution`'s
"What IS A Blocker" set (user authority, human decision, missing secret after
local scan, out-of-scope boundary, external dependency, safety/compliance,
genuinely-missing information), and for these never-unlock actions:

- Committing or exposing **secrets**.
- **Force-push** or any history-destroying / irreversibly-destructive operation
  (dropping data you did not create, `reset --hard` over others' work,
  destructive infra changes).
- Editing or acting on **another repository**, service, or system you were not
  pointed at.
- **Spending money** or any irreversible outward action that is not shipping this
  work.
- **Stopping, restarting, or rebinding a live public service.** If the service
  manifest (`services.json`) marks a provided service `runtime.public: true`
  or `restart_requires_consent: true`, taking it down — even briefly, even to
  fix it — requires explicit user consent in EVERY tier. And any service
  launch must use the manifest's declared `runtime.bind_host` (e.g.
  `0.0.0.0`); never default to loopback for a declared service (REQ-122: a
  loopback relaunch took live websites down).

The hard floor is the definition of a "real blocker" for `autonomous` mode: in
that tier you stop *only* for it.

## Part 4: Decide in two stages

**Stage 0 — Can you answer it yourself?** Before *any* escalation to the user,
if the open question is a **findable fact**, follow the ordered self-service
ladder: **Capability discovery**; connected **Substrate memory**/recall; the
**LLM wiki**; canonical PRD records through tools; then **Raw repository search**
and git history, local files, and web tools. Widen to raw sources whenever higher
level recall is unavailable, stale, contradictory, or insufficiently precise.
Only carry a factual question to Stage 1 if every applicable source genuinely
comes up empty, then state what you checked. See
`.prd_plugin/method/self-service.md`. This never lowers the floor, and a genuine
user-only preference remains a legitimate ask.

**Stage 1 — Is this mine to decide?** (the gate, tier-aware)

1. Is it on the **hard floor** (Part 3)? → stop and escalate via
   `project-blocker-resolution`, in every tier.
2. Is it **shipping the work** (push / merge / publish)? → in `autonomous`, do it
   once the gate is green; in `key_decision` / `guided`, get explicit consent.
3. Does the configured tier require a check for this class of decision (Part 2)?
   → propose and confirm.
4. Otherwise it is yours — proceed to Stage 2.

**Stage 2 — Make the highest-quality decision.** Hold the choice against
CRAFTESB, not just the first plausible option:

- **Correct** — accurate and sound; it actually works.
- **Robust** — durable; handles edge cases and survives foreseeable change.
- **Aligned** — serves the user's actual goal/intent, not a locally-correct
  adjacent problem.
- **Faithful-to-method** — fits PRD Plugin rules, existing `DEC-*` decisions,
  repo conventions, and the relevant skill instructions; if it contradicts a
  durable decision, supersede it explicitly via `project-decision-ledger`.
- **Tested** — you can prove it is right, not just believe it (tie to
  `project-evidence` / `project-verification-before-completion`).
- **Efficient** — use the smallest sufficient implementation that preserves the
  full intended behavior and quality bar. Prefer less code, fewer files, less
  state, and fewer abstractions when they produce the same verified result.
  Efficient bounds the size of the **solution**; it never licenses delivering
  less than what was asked for — that is Bounded's job, and Bounded bounds the
  other direction.
- **Bounded** — solve the problem you were asked to solve, at the size you were
  asked to solve it. Before building, **name the smallest thing that satisfies
  the literal ask**. If what you are building is bigger than that, say in one
  line what the extra buys and who asked for it. *"We might need it later"* is
  not an answer — file it.

  Scope inflation, concretely — all of these are failures:
  - generalising to N cases when one case was asked for;
  - adding configuration, options, or extension points for a choice nobody has
    actually had to make yet;
  - an abstraction, layer, or registry whose only caller is hypothetical;
  - producing design artifacts (brainstorms, option matrices, requirement
    lists, open questions) when the ask maps to a small concrete mechanism;
  - handing the user questions instead of working software;
  - solving adjacent problems you noticed on the way — **file those as
    `REQ-*`, do not build them into this change**.

  Bounded is **not** permission to under-deliver. It bounds the *problem*,
  never the quality bar: tests, evidence, the consent floor, and the rest of
  CRAFTESB still apply in full. A gap *inside* the ask gets fixed now; a new
  problem *outside* the ask gets filed. If you cannot state the smaller
  alternative you rejected, you have not considered one.
- **Secure** — the change cannot be turned against the user or the system:
  secrets stay out of code, logs, state, and transport; boundaries **fail
  closed** (unknown or malformed input is refused, never guessed); **least
  privilege** by transport (read surfaces stay read-only, mutations go through
  validated, locked paths); and the **blast radius** is bounded to what was
  asked for — no writes outside the repo you were pointed at, no foreign
  records planted in someone else's state. Load-bearing wherever a change
  crosses a boundary (transport, service bindings, tool surfaces, credentials,
  destructive or exposing actions); a no-op for purely internal work.

## Part 5: Proportion deliberation to stakes

Spend rigor in proportion to reversibility and impact. A trivial, reversible
choice gets a one-line check. A high-stakes or irreversible one gets the full
Stage-2 bar plus a second independent pass (re-derive it, or argue the opposite,
before committing). Running the full bar on every trivial decision is its own
failure.

## Recording autonomous decisions

When a decision is durable, record it with `project-decision-ledger` and set
`decided_by` to `autonomous`, `human_approved`, or `user_requested`, and
`autonomy_tier` to the tier in effect. This makes the autonomy trail auditable —
reviewers can tell which decisions were agent-made versus human-vetted.

## Staleness Coverage

Before relying on a prior decision to set your autonomy or route, check whether
the governing `DEC-*`, `REQ-*`, or config policy is stale or superseded; a stale
decision is not authority. Apply `.prd_plugin/method/staleness-rules.md`.

## Red Flags

- Starting `project-planning-lifecycle` for a one-line fix, or skipping it for
  genuinely new scope.
- Patching a third bug in a row in the same area without re-grounding — three
  fixes that each WORKED and each revealed another means the model of the
  system is wrong, and more patches cannot repair a wrong model
  (`project-systematic-debugging` → the circuit breaker).
- Treating `autonomous` as "skip the quality bar" rather than "move the ask
  threshold".
- Crossing the **hard floor** because the tier is high (secrets, force-push,
  another repo, and irreversible outward spend never unlock).
- Stopping to ask permission to **ship** in `autonomous` — once the gate is green,
  push / merge / publish is the work, not a floor question.
- Shipping in `key_decision` / `guided` without explicit consent, or shipping red
  in any tier.
- Deciding a key/irreversible matter silently in `key_decision` or `guided`.
- Recording a durable decision without `decided_by` / `autonomy_tier`.
- Stopping in `key_decision` to ask something the method, the plan, or the
  repo already answers — that is not a key decision, and the continue guard
  will block it (REQ-150).
- Ending a completed step with "shall I proceed?" / "which would you prefer?" in
  `autonomous` — continuing the planned work is not a decision to escalate.
- Opening a report with ID codes instead of a plain-language summary (see
  `.prd_plugin/method/reporting.md`).
- Starting with raw repo/history search without first discovering available
  tools, checking connected Substrate memory/recall, querying the LLM wiki, and
  reading canonical PRD records through their validated interfaces.
- Using subagents without both explicit user authority and host/runtime
  permission, or violating `.prd_plugin/method/subagents.md`.
- Nagging the user to wrap up, hand off, or close the session because it's been
  long or your context is filling — session length and context pressure are never
  reasons to stop; the harness compacts context for you.