---
name: project-blocker-resolution
description: Use when work cannot continue without external authority, a missing human decision, an out-of-scope boundary, or a dependency that the agent cannot resolve itself. Declares the blocker, exhausts local resolution paths, routes it to the right artifact, and records what would unblock it.
---

# Project Blocker Resolution

Use this skill to distinguish between "hard" and "need help" stops, and to
handle the hard ones without silent stalling.

## Iron Law

```text
NO BLOCKER WITHOUT FIRST EXHAUSTING LOCAL RESOLUTION PATHS
```

A blocker is a stop that requires authority, input, or action the agent does not
have. Most things that look like blockers are not.

## What Is NOT A Blocker

Do not declare a blocker for any of these until you have tried the listed
resolution:

| Symptom | Local Resolution |
| --- | --- |
| Missing dependency | Download and install it; add it to `requirements.txt`, `package.json`, etc. |
| Service/server not running | Start the service. If it needs a config file, generate or derive it from repo templates. |
| Tool installed but not on PATH | Call it by full path, or add the directory to `PATH` for the current process. |
| Missing config/credentials | Read `.env`, `.env.example`, `.env.local`, `config.json`, `config.yml`, `.prd_plugin/config.json`, `~/.config/<app>/`, Windows Credential Manager, macOS Keychain, Linux secret-service, and known CLI profiles (`gh auth status`, `aws configure list`, `gcloud config list`, etc.). |
| Missing generated file | Generate it from templates or existing source. |
| Missing information in repo | Search docs, state, history, issue tracker exports, and request threads. |
| Task is hard or large | Break it down; use `project-implementation-plan`. |
| Test fails | Debug it; use `project-systematic-debugging`. |
| Two existing decisions look contradictory | Re-read the decision records; the newer one may supersede the older. |

If the issue resolves through any of the above, it is not a blocker. Record the
fix in the relevant `TRK-*`, `CHG-*`, `EV-*`, or `REQ-*` as normal.

## What IS A Blocker

A blocker is one of the following:

1. **User authority required**: cost, scope change, destructive action,
   committing/pushing to a repo not explicitly authorized, or modifying
   production/deployment infrastructure.
2. **Human decision required**: ambiguous product direction, conflicting
   architecture choices that need owner resolution, legal/licensing changes, or
   policy exceptions.
3. **Missing secret/credential after local scan**: the credential is not in any
   local source listed above, and the agent cannot generate, request, or derive
   it without user help.
4. **Out-of-scope boundary**: the fix requires editing a different repo,
   service, or system the user did not point at or authorize.
5. **External third-party dependency**: requires a human account, contract,
   API access approval, or vendor action.
6. **Safety or compliance risk**: proceeding without explicit sign-off would
   violate safety, privacy, legal, or repo policy.
7. **Information genuinely unavailable**: no source in the repo, its history,
   or local config can answer the question, and the user must supply it.

## Workflow

### Phase 1: Exhaust Local Resolution

- State the symptom precisely.
- Try the resolutions in the "What Is NOT A Blocker" table.
- For credentials, document which local sources were checked.
- For services, document the start command attempted and its result.
- For dependencies, document the install command attempted and its result.

If any step resolves the issue, stop here and continue the original task.

### Phase 2: Classify The Blocker

Pick one category:

- `user_authority_required`
- `human_decision_required`
- `missing_credential_after_local_scan`
- `out_of_scope`
- `external_dependency`
- `safety_or_compliance`
- `missing_information`

### Phase 3: Route To The Right Artifact

| Category | Target Artifact |
| --- | --- |
| `user_authority_required` | `REQ-*` through `project-request-intake` if the user must approve; include exactly what you want permission to do. |
| `human_decision_required` | `DEC-*` through `project-decision-ledger` if options are known; otherwise `REQ-*` asking for the decision. |
| `missing_credential_after_local_scan` | `REQ-*` with the local sources checked and the exact credential or env var needed. |
| `out_of_scope` | `BLK-*` record linked to the active `TRK-*`, plus a `REQ-*` or `HLT-*` if the boundary is risky. |
| `external_dependency` | `BLK-*` record with the third-party action required; link to `TRK-*`. |
| `safety_or_compliance` | `HLT-*` through `project-health` with status `blocked`; do not proceed without explicit sign-off. |
| `missing_information` | `REQ-*` with the specific question and why repo state cannot answer it. |

### Phase 4: Record The Blocker

Create a `BLK-*` record in `.prd_plugin/state/blockers.json` with:

1. `id`: `BLK-###`
2. `status`: `active`, `resolving`, `resolved`, `escalated`, `carried_forward`, or `superseded`
3. `category`
4. `description`: what is blocked and why
5. `blocks`: list of `TRK-*`, `IMP-TASK-*`, or other work IDs
6. `local_resolution_attempted`: commands, scans, or paths tried
7. `routed_to`: `REQ-*`, `DEC-*`, `HLT-*`, etc.
8. `unblock_criteria`: exactly what would allow work to resume
9. `owner_agent` as `AGENT-*`, `created_from_session` as `SES-*`
10. `created_at`, `updated_at`, `resolved_at` when applicable
11. `resolution_summary` and `evidence_ref` when resolved

### Phase 5: Report Or Hand Off

If resolved: update downstream `TRK-*` status and continue.

If not resolved: report to the user:

- What is blocked.
- The category.
- What you already tried.
- The exact permission, decision, or information needed.
- The `BLK-*` and `REQ-*`/`DEC-*`/`HLT-*` IDs created.

**In `autonomous` tier**, the run-until-done Stop guard (`prd_stop_guard.py`) will
otherwise push you to keep working. To hand a genuine blocker back to the user,
create the marker file `.prd_plugin/local/autonomy-pause` with a one-line reason
(e.g. the `BLK-*` id and what you need) before you stop — the guard then allows
the session to stop and clears the marker. This is the supported way to escape the
loop for the consent floor; see `project-decision-policy` → "Run-until-done".

## Staleness Coverage

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


Before declaring a blocker, check whether the same symptom already has an open
`BLK-*`, `REQ-*`, `HLT-*`, or `TRK-*`. If so, append a `MSG-*` to the existing
thread or update the existing `BLK-*` instead of creating a duplicate.

## Boundaries

- Do not cross repo/service boundaries without explicit user direction.
- Do not spend money, create paid accounts, or sign agreements.
- Do not fabricate credentials or secrets.
- Do not treat "I don't want to try" as a blocker.
- Do not silently stall: declare the blocker or resolve it.

## Output Shape

When reporting blocker work, include:

1. Whether the issue was resolved locally.
2. The `BLK-*` ID if one was created.
3. The category and target artifact (`REQ-*`, `DEC-*`, `HLT-*`).
4. The local resolution attempts made.
5. The exact unblock criteria.