| name | np-reading-issues |
| description | Use when the agent needs to understand a specific `np` (nitpicking) issue (typically right after claiming it), explore the issue's parent, siblings, or `refs` neighbours for context, look up an issue by ID, view its history, search for issues by text, or list issues by label or other filters. Triggers on prompts like "what does FOO-a3bxr cover", "what do I need to do for this issue", "do we already have an issue for X", "show me the history of FOO-a3bxr". |
np-reading-issues
Overview
np exposes three reading activities, in priority order:
- Understand a specific issue — typically after claiming it, to know what to work on.
- Discover the issue's key relationships — parent, siblings, and
refs neighbours often carry context the issue body assumes.
- Find arbitrary issues by text or label — duplicate checks, "do we already have an issue covering X", workspace surveys.
All read commands work without a claim.
Understanding a specific issue
np show <ID> is the workhorse. It returns full detail: state, readiness, priority, labels, parent, relationships, comments, and the audit-relevant fields.
$ np show FOO-a3bxr
$ np show FOO-a3bxr --json
When the issue's evolution matters — for example, when reasoning about decisions captured in earlier comments — read its history:
$ np issue history FOO-a3bxr
Together, np show and np issue history are usually sufficient for "what do I need to do for this issue".
Exploring an issue's key relationships
The issue alone often does not carry enough context. Three readings around it are usually worth doing:
Parent. If np show <ID> reports a parent, read it for the broader goal:
$ np show <PARENT-ID>
Siblings. Other children of the same parent often share assumptions, ordering, or vocabulary:
$ np epic children <PARENT-ID>
refs neighbours. refs is the informational link np uses for "see also" relationships. The issue may point at related-but-not-blocking work that explains intent:
$ np rel issue <ID>
Decide which of the three to read based on what the issue's text leaves unexplained. Reading the parent matters more for child tasks of a focused epic; reading siblings matters more when ordering or shared design is implied; reading refs matters when the issue cites a precedent.
Finding arbitrary issues
When the goal is not "understand this issue" but "find issues about X" — for duplicate checks, surveys, or answering "do we have an issue for this?":
$ np issue search "login timeout"
$ np issue search "timeout" --label area:api
$ np list --label kind:bug --label area:auth
$ np list --state deferred --label defer-reason:unclear
$ np list --role epic --state open
np list accepts --role, --state, --parent, and repeated --label flags (AND-combined; key:* matches any value for a key). --columns and --order control table output:
$ np list --columns ID,PRIORITY,TITLE
$ np list --order MODIFIED:desc
Prefer --json whenever a script will parse the result:
$ np list --label kind:bug --json
$ np show <ID> --json
What this skill does not cover
- Claiming work — use
np-finding-work. This skill is read-only.
- Modifying labels to make filtering work better — use
np-labeling.
- Adding relationships discovered during reading — use
np-managing-relationships.
- Diagnosing why nothing is ready — out of scope; the agent's stance is "either work is ready or it isn't".
Common mistakes
- Stopping at
np show <ID> when the issue's body is thin. Many tasks assume parent or sibling context. Spend a minute reading the parent and at least one sibling before working.
- Searching with
np list and forgetting np issue search. np list filters by structured fields and labels; np issue search is the free-text path. Use both when looking for prior work.
- Calling read commands with
--author flags. Reads do not take --author and do not require a claim.
