shepherd: follow-up
You found work that is real and worth doing, but it does not belong in the current change. Write it up so a future session can start from it, then go back to the current work without widening it.
Adapted from the file-followup-issue skill in pydantic-ai.
Gate: all three must hold
- The current change does not need it. It closes its own issue or story without this.
- It is real and verified. You reproduced the bug or confirmed the gap with evidence: a failing command, a query result, a
file:line. A hunch that "others might also be affected" is not a follow-up; verify it first, or mention it in one line as unverified and stop.
- It is non-trivial and out of scope. Fixing it here would add its own design decisions, carry open questions, or reach code the current change does not touch.
If a gate fails, do the alternative and stop:
- Trivial and in scope: fix it in the current change.
- In scope but larger: add it to the current plan.
- Not a real problem: drop it.
Steps
Find the tracker. Use the one the current work comes from: a GitHub issue → GitHub; a Jira story → Jira. If there is no current work, use GitHub when the repo has a GitHub remote, else ask.
Dedup.
- GitHub:
gh issue list --state all --search "<3-5 distinctive keywords>" --limit 20.
- Jira: search with a Jira or Atlassian MCP tool when one is connected.
If a clear match exists, link it instead of filing a new one, and skip to step 5.
Draft the title and body with the template below. Write each to a file with your editor tool, never into a shell argument: quoted code and reviewer text can contain $(...) and backticks that the shell would run.
Confirm, then create. Filing is outward-facing. Show the user the title and body and wait for a yes.
- GitHub:
title=$(cat <title file>) then gh issue create --title "$title" --body-file <body file>. Add labels only if gh label list shows they exist.
- Jira: create it through the connector only on that yes. If no connector works, give the user the draft to paste.
Log the deferral so reviewers of the current change see why it was parked:
- /shepherd/run active on this branch:
shepherd decision --title "defer: <short title>" --decision "Filed as <link> instead of fixing here" --why "Out of scope: <decisions | open questions | reach>" --source <link>.
- /shepherd/diagnose active: add it under Fix direction → out of scope in the write-up, with the link.
Report the link in one line. Do not expand the current change.
Issue body template
## Background
<what we were doing and where this surfaced; link the originating PR, story, or diagnosis>
## The problem
<the bug or improvement, concrete and specific>
## Evidence
<how it was verified: the command and its output, the query result, or the failing test>
## Why it's out of scope for the originating change
<the specific reason: its own design decisions, open questions, or reach>
## Where
- `path/to/file.py` — `Class.method` <!-- file and symbol, no line numbers: they drift -->
## Suggested direction (low confidence)
<optional starting point, marked as a lead, not a decision. Omit if you have none.>
1---2name: followup3description: Park a real bug or improvement found while working on something else — out of scope for the current change, but worth doing — as a GitHub issue or a Jira story draft, with enough context that a fresh session can pick it up cold. Does not touch the current change. Use when /shepherd/run, /shepherd/diagnose, or a review turns up a side issue. Not for trivial in-scope fixes (just do them) or for hunches (verify them first).4argument-hint: "<the side issue, in a sentence>"5metadata:6 source: https://skillmd.com/skills/rohaquinlop/followup7---89# shepherd: follow-up1011You found work that is real and worth doing, but it does not belong in the current change. Write it up so a future session can start from it, then go back to the current work without widening it.1213Adapted from the `file-followup-issue` skill in [pydantic-ai](https://github.com/pydantic/pydantic-ai).1415## Gate: all three must hold16171. **The current change does not need it.** It closes its own issue or story without this.182. **It is real and verified.** You reproduced the bug or confirmed the gap with evidence: a failing command, a query result, a `file:line`. A hunch that "others might also be affected" is not a follow-up; verify it first, or mention it in one line as unverified and stop.193. **It is non-trivial and out of scope.** Fixing it here would add its own design decisions, carry open questions, or reach code the current change does not touch.2021If a gate fails, do the alternative and stop:2223- Trivial and in scope: fix it in the current change.24- In scope but larger: add it to the current plan.25- Not a real problem: drop it.2627## Steps28291. **Find the tracker.** Use the one the current work comes from: a GitHub issue → GitHub; a Jira story → Jira. If there is no current work, use GitHub when the repo has a GitHub remote, else ask.302. **Dedup.**31 - GitHub: `gh issue list --state all --search "<3-5 distinctive keywords>" --limit 20`.32 - Jira: search with a Jira or Atlassian MCP tool when one is connected.3334 If a clear match exists, link it instead of filing a new one, and skip to step 5.353. **Draft** the title and body with the template below. Write each to a file with your editor tool, never into a shell argument: quoted code and reviewer text can contain `$(...)` and backticks that the shell would run.364. **Confirm, then create.** Filing is outward-facing. Show the user the title and body and wait for a yes.37 - GitHub: `title=$(cat <title file>)` then `gh issue create --title "$title" --body-file <body file>`. Add labels only if `gh label list` shows they exist.38 - Jira: create it through the connector only on that yes. If no connector works, give the user the draft to paste.395. **Log the deferral** so reviewers of the current change see why it was parked:40 - /shepherd/run active on this branch: `shepherd decision --title "defer: <short title>" --decision "Filed as <link> instead of fixing here" --why "Out of scope: <decisions | open questions | reach>" --source <link>`.41 - /shepherd/diagnose active: add it under **Fix direction → out of scope** in the write-up, with the link.426. **Report** the link in one line. Do not expand the current change.4344## Issue body template4546```markdown47## Background48<what we were doing and where this surfaced; link the originating PR, story, or diagnosis>4950## The problem51<the bug or improvement, concrete and specific>5253## Evidence54<how it was verified: the command and its output, the query result, or the failing test>5556## Why it's out of scope for the originating change57<the specific reason: its own design decisions, open questions, or reach>5859## Where60- `path/to/file.py` — `Class.method` <!-- file and symbol, no line numbers: they drift -->6162## Suggested direction (low confidence)63<optional starting point, marked as a lead, not a decision. Omit if you have none.>64```