sysadmin
daf9910e83
- Updated llm-project-workflow/SKILL.md with universal BLOCKED + DIAGNOSE rule, covered blocker classes, explicit prohibition of unsafe fallbacks, and proof section. - Added templates/blocked-diagnose-report.md (standard template with all required fields). - Updated workflows/work-issue.md, review-merge-pr.md, create-issue.md and templates/start-issue.md, review-pr.md, merge-pr.md, recover-bad-state.md to require and reference the rule at load. - Updated docs/llm-workflow-runbooks.md to reinforce the rule for controller prompts and all workflows. - All changes in isolated worktree branches/issue-552-blocked-diagnose. No root mutation. No unsafe fallbacks used. - Tests (workflow + cleanup proofs): 26+ passed in run. - git diff --check prgs/master...HEAD: clean.
52 lines
3.1 KiB
Markdown
52 lines
3.1 KiB
Markdown
# Blocker Report Template (BLOCKED + DIAGNOSE)
|
|
|
|
Use this exact structure whenever a required workflow step cannot be performed. Emit this report and stop. Do not proceed to mutation or fallback unless a controller explicitly authorizes an exception in writing.
|
|
|
|
## Required step
|
|
<Describe the exact step, skill, tool, capability, instruction, profile, or preflight that was required. Include the canonical name and where it is defined (e.g. gitea-workflow skill, specific workflow file, gitea_xxx tool).>
|
|
|
|
## Observed failure
|
|
<Exact symptom, error message, missing output, guard error, 404, schema error, dirty state, wrong profile, etc. Quote relevant output or tool response.>
|
|
|
|
## Expected behavior
|
|
<What the workflow/docs/prompts say should happen. Reference the specific rule, template, or preflight that requires this step.>
|
|
|
|
## Checks performed
|
|
- List every verification attempted (e.g. gitea_whoami, resolve_task_capability, ls skills/, git status, mcp_list_*, worktree list, etc.)
|
|
- Note any discrepancies found (e.g. skill not mounted for this runtime, capability not in profile, cwd not under branches/, etc.)
|
|
|
|
## Safe recovery attempted
|
|
- Only non-mutating actions (reads, lists, views, status, whoami, resolve, fetch --dry, etc.)
|
|
- List what was tried and the result.
|
|
- If no safe recovery possible, state that explicitly.
|
|
|
|
## Likely classification
|
|
Choose one or more:
|
|
- missing required skill or workflow guide
|
|
- broken terminal/tool runner
|
|
- MCP capability failure or deadlock
|
|
- wrong profile or role
|
|
- dirty or misbound worktree
|
|
- root checkout mutation risk
|
|
- mutation guard failure
|
|
- missing required MCP tool/schema
|
|
- stale or inconsistent runtime state
|
|
- unavailable project instructions
|
|
- other: <describe>
|
|
|
|
## Durable fix recommendation
|
|
<Specific, actionable recommendation that fixes the root process/tooling issue (e.g. "Mount gitea-workflow skill for Codex under canonical name in ~/.codex/skills/", "Add preflight in llm-project-workflow/SKILL.md that hard-stops before any gitea_ call if X is unavailable", "Update controller prompt to require BLOCKED + this report before any fallback", "Grant capability in profile config", etc.). Do not suggest temp workarounds.>
|
|
|
|
## Mutation occurred?
|
|
- No (preferred and required unless explicitly authorized)
|
|
- Yes — describe exactly what was mutated and why it was unavoidable after diagnosis. (This should be rare and will trigger additional review.)
|
|
|
|
## Single next action
|
|
<One concrete next step for the current actor (e.g. "Controller to approve or reject recovery", "File follow-up issue #XXX for skill mounting", "Re-launch session from clean branches/ worktree after skill installed", "Stop and wait for profile update").>
|
|
|
|
---
|
|
|
|
**Rule reminder (do not bypass):**
|
|
If the required step is unavailable, you are BLOCKED. Diagnose using this template. Report. Stop. Unsafe fallbacks (temp scripts, direct API, MCP internals, direct imports, in-memory restoration, manual bypasses) are prohibited unless a controller has authorized them for this specific instance in a prior handoff.
|
|
|
|
This report must appear in the final output / handoff before any further action. |