workflow-failure-auto-issue

Workflow Failure → Auto-File Issue

workflow-failure-detector.cjs (SubagentStop hook) auto-detects failures. AI-emitted markers are the fallback.

Pipeline: emit a marker in your message text → lesson-collector.cjs Stop hook captures it → enqueued to pending-skill-updates.jsonl → end-of-session detached flush (skill-bug / mcp-gap → gh issue create; lesson → next UserPromptSubmit reminder + background /t1k:sync-back). lib/lesson-flush-runner.cjs covers skill-bug/mcp-gap when no further UserPromptSubmit fires (#334). Detail: docs/workflow-failure-auto-issue.md.

Rule

If you observe any failure mode below AND the hook didn’t auto-detect it (no [t1k:workflow-failure-detected] stdout), emit the matching marker BEFORE moving on:

Failure mode	Marker type
Agent stops mid-task without writing declared deliverable	`[t1k:skill-bug ...]`
Skill body cannot fulfill its stated purpose in context	`[t1k:skill-bug ...]`
Agent modifies files outside its declared scope	`[t1k:skill-bug ...]`
Plan-file claim found factually wrong during execution	`[t1k:lesson ...]`
MCP tool returns “unknown action” / missing-parameter gap	`[t1k:mcp-gap ...]`
Agent type definition leads to predictable failure mode	`[t1k:skill-bug ...]`
Kit-owned skill applied by reading `SKILL.md` (no `Skill` tool call, so `skill-validity-reminder.cjs` never fired) and its guidance was stale	`[t1k:skill-bug ...]`

Marker format (ALL attributes required — regex silently rejects partial markers):

[t1k:skill-bug kit="<kit>" skill="<skill-or-agent>" bug="<one-line>" evidence="<path-or-id>"]
[t1k:lesson kit="<kit>" skill="<skill>" fragment="<file-or-section>" reason="<one-line>"]
[t1k:mcp-gap kit="<kit>" tool="<tool>" gap="<one-line>" evidence="<reproduction>"]

Marker MUST appear in assistant message text (NOT a tool call or file). Stop hook parses message text only.

Do NOT emit for

Tool errors the hook already handles · partial markers · inline /t1k:issue calls (markers + background sub-agent is the canonical path) · a skill/agent that is correct and helpful · evergreen guidance with no version surface · a one-off preference difference that isn’t actually wrong · trivia, transient errors, or already-documented issues.

Dual-action (#341)

Mid-session marker emission MUST also spawn /t1k:issue (skill-bug/mcp-gap) or /t1k:sync-back (lesson) in the SAME turn. Stop-hook queue is end-of-session safety-net only.

Manual-vs-auto dedup: after any manual /t1k:issue filing, call markSubmitted(fingerprint, issueUrl) — see skills/t1k-issue/references/file-manual.md § “After filing”.

Full rule, anti-patterns, spawning-agent brief template, and SubagentStop hook details: docs/workflow-failure-auto-issue.md + docs/auto-issue-pipeline.md § Dual-action.