| name | next-best-action |
| description | Pre-close checklist that catches findings that should be filed as tickets before the close commit. Run before every `npm run close N` on any substantive puzzle. |
/next-best-action -- pre-close finding checklist
Invoke this skill before writing the close commit and before running npm run close N. It takes 2-3 minutes and catches the most common oversight: findings that should become tickets, but won't if you close now.
Run only with explicit user go-ahead. This is a token-heavy pass, so don't auto-run it on every close and don't auto-skip it by how long the turn took. At close, surface that it applies ("next-best-action would apply here -- run it?") and run it only once the user approves. The cost control is the approval gate, not a duration heuristic (#1279).
Trigger
Every substantive puzzle close -- any ticket whose work produced code changes, doc changes, research findings, or process observations.
Skip when
- Pure velocity-log-only commits (no scope change, just a CSV update)
- Pure PM/triage sessions with no code or doc output
(Duration is not a skip reason — a sub-minute close can still hide a fileable finding. The gate is user approval, not turn length; see the approval note above.)
Existence check
Before running the checklist, verify the skill file you are about to evaluate actually exists on disk. A ticket that "delivered" a skill (e.g., #1067 closed with "next-best-action done") does not guarantee the file was written. If the target skill is missing:
- Check
~/.hermes/skills/<category>/<name>/SKILL.md
- If absent, create it from the Claude source at
~/.claude/skills/<name>/SKILL.md before proceeding
- This is a one-time bootstrap — subsequent Q1-Q6 runs will have the file available
Input (read before answering)
git diff origin/main -- what actually changed vs. the ticket's "Should have"gh issue view N -- the ticket title and scope boundary- Your closing summary -- what you observed, decided, and deferred during this session
The checklist -- answer each question
For every YES: name the finding and the ticket shape. Filing is mandatory -- a wrong ticket can be closed immediately after filing.
Q1 -- Bug or regression
Did you encounter a bug, parity deviation, or regression that is NOT in this ticket's stated scope?
- Yes -> file a bug ticket now:
gh issue create --title "bug: ..." --label "bug,severity:medium"
- No -> clear.
Q2 -- Process recurrence
Did a known failure mode recur this session? Did you state any intent -- "I'll file a ticket", "I'll post a comment", "I'll update the doc" -- and then not follow through?
- Yes -> file a process-improvement ticket. Reference the failure mode by name if it appears in
docs/research/orchestration-failure-modes.md.
- No -> clear.
Q3a -- Doc contradiction
Does your output contradict or extend an existing doc, TIL, glossary entry, or open ticket?
- Yes -> file a WRITER ticket to update the doc, or post a correction comment on the open ticket.
- No -> clear.
Q3b -- Closing loop
Did you post a closing comment on the issue? If you filed a child ticket, does it include **Parent:** #N in its body?
- Closing comment missing -> post it now:
gh issue comment N --body "Closed in <sha>. <summary>"
- Child ticket missing parent link -> edit now:
gh issue edit <child-N> --body "**Parent:** #N\n\n<rest of body>"
- Both present -> clear.
Q4 -- Deferred decision
Did you defer a technical or process decision with no tracking ticket?
If this is a research or spike close: did you file a child DEV/SPIKE ticket for each concrete proposal? A research close with N proposals and zero children is half-finished; the findings exist but have no path to implementation. (Rule source: claude_workflow.md step 4, #621.)
- Yes -> file a decision or DEV ticket now.
- No -> clear.
Q5 -- External routing
Is there a follow-up question for a human, Charlie, or Prof. Dos Reis that has no waiting-on-external ticket?
- Yes -> file a ticket labeled
waiting-on-external. Include the handle of who needs to respond.
- No -> clear.
Q6 -- Error self-audit (RULES.md 16 / R021)
Re-read your session from claim to now. Did any tool/Bash/git/gh/claim call fail, any hook block, any permission get denied, or any schema/validation check fail this session -- including ones you retried and resolved?
- Yes -> confirm each has an
errors row or log it now via npm run error:log -- '{"ticket":N,"error_type":"...","message":"..."}'.
- Either way -> state the outcome in the closing comment:
error self-audit: N row(s) logged or error self-audit: no loggable errors this session. (Silence is not a pass -- that is the #1108/#1117 failure mode.)
Verification Checklist
Before you start, confirm you can answer all 6:
One-Shot Recipe
1. git diff origin/main # what changed
2. gh issue view N # ticket scope
3. Answer Q1-Q6 # one by one, file as needed
4. GREEN or AMBER # all clear or list filings
5. npm run close N # only after GREEN
Output format
All questions answered -> emit one of:
GREEN -- all clear. Proceed with npm run close N.
or
AMBER -- file before closing:
- Q1: <finding> -> bug: <title stub> (label: bug, severity:medium)
- Q3b: no closing comment posted on #N
(filing is not optional -- a wrong ticket can be closed immediately)
Only proceed to npm run close N after reaching GREEN, or after filing tickets for every AMBER item and re-confirming.
Real-world examples (from lccjs session history)
| Human follow-up that this skill should have prevented | Caught by |
|---|
| "pls file a ticket, this process isn't being followed consistently" | Q2 -- process recurrence unfiled |
| "why didn't you follow through?" | Q2 -- stated intent not acted on |
| "did you leave a closing comment on the ticket?" | Q3b -- no closing comment |
| "child ticket missing parent link / no comment on #634" | Q3b -- cross-reference omitted |
| "is there a follow-up ticket to decide what to do about orchestration failure modes?" | Q4 -- research closed with zero children |
| "pls file a tracker with the 13 mitigations" | Q4 -- N proposals, zero children |
| "pls create a decision ticket for the #611 audit results" | Q4 -- audit closed with no decision ticket |
| "file a ticket for the blocked closing comment process-improvement" | Q2 + Q5 -- blocker not filed, routing skipped |
Related
docs/claude_workflow.md step 5 -- where this skill is wired into the close sequence- M3 (#627) -- prose checklist companion (teaches the same questions; this skill enforces them)
docs/research/orchestration-failure-modes.md -- failure mode catalogue for Q2 naming
@todo — generalize beyond lccjs
lccjs is the only consumer today. When porting, parameterize:
npm run close / npm run error:log are lccjs commands.- Doc references (
docs/research/…, claude_workflow.md, RULES.md) point at lccjs files.
- Example issue numbers in the text are lccjs tickets.
