Document Issues

Documenting follow-up issues

Use this skill while working in a git repository when an unrelated issue is worth preserving for later follow-up.

Default behavior

Prefer GitHub issues as the system of record.

Default to asking before creating anything unless the user explicitly enabled autonomous issue capture for the current conversation.

Treat nytid todo import as an optional second step after creating a GitHub issue, not as the default capture path.

What to capture

Capture only issues that are:

• unrelated to the current task
• actionable enough to describe clearly
• valuable to revisit later

Typical examples:

• an unrelated bug
• missing tests discovered while fixing something else
• a cleanup/refactor item that should not be folded into the current change
• misleading docs or comments
• tooling or CI friction uncovered during the task

Do not create a follow-up issue when:

• the current task already includes fixing it
• the observation is too vague to be actionable
• there is no repository context
• the repository is not GitHub-backed or issue creation is unavailable

Preferred workflow

1. Confirm that issue capture makes sense

When autonomous issue capture is not enabled, ask a short confirmation before creating anything.

Recommended wording:

I found an unrelated follow-up issue in this repo. Want me to file a GitHub issue for it?

If the user has stated a session preference to also import created GitHub issues into nytid todo, honor that after issue creation.

2. Verify repository and GitHub context

Check that the current directory is inside a git repository:

git rev-parse --is-inside-work-tree

Resolve the GitHub repository and ensure issues are enabled:

gh repo view --json nameWithOwner,url,hasIssuesEnabled

If this fails or hasIssuesEnabled is false, do not create a GitHub issue. Offer nytid todo only if the user asked for it or GitHub issue creation is not available and they still want the follow-up captured.

3. Check for likely duplicates

Search existing issues before creating a new one. Use a short query built from the most specific keywords in the proposed issue title.

gh issue list --state all --search "<keywords>" --json number,title,url,body

If a likely duplicate exists, show it to the user instead of creating a new issue unless they explicitly want another one.

4. Create the GitHub issue

Use noninteractive creation.

gh issue create --title "<title>" --body-file -

Prefer existing labels when clearly applicable. Do not create new labels automatically.

Issue bodies should be concise but preserve the context that made the issue worth filing.

Use this structure:

## Context
What work was in progress when this came up?

## Observation
What problem, gap, or follow-up item was discovered?

## Why it matters
Why should this be addressed later?

## Evidence
Files, commands, error messages, or behavior that support the observation.

## Suggested follow-up
The most likely next step, without overcommitting to a solution.

When possible, include concrete file paths, function names, commands, and behavior observed during the current task.

5. Optionally import into nytid todo

If the user enabled the session preference to also import created GitHub issues into nytid todo, import the created issue after it is filed.

Always pass --who dan-claude for nytid operations.

Preferred import pattern:

nytid todo import <owner/repo> --number <issue-number> --who dan-claude --here --github-labels

Use gh issue create as the source of truth. If the returned output does not reliably expose the issue number, resolve it by exact title with gh issue list before importing.

Do not modify todo items assigned to other workers.

Closing the loop: reference issues from PRs and commits

Filing is half the lifecycle; the other half is making sure fixes close their issues automatically.

When creating a PR (or commit) that addresses a filed issue, include a closing keyword in the PR body: Fixes #N (also Closes #N / Resolves #N). GitHub then closes the issue when the PR merges. Before opening any fix PR, check the tracker for an issue it resolves — the search from step 3 works in this direction too. A fix derived from an internal finding that was never filed as an issue needs no keyword; do not file an issue just to close it.

When a PR only partially addresses an issue or adds evidence to it, use a plain reference (#N, or "part of #N") instead of a closing keyword, and leave the issue open.

Watch for the stale case: an already-merged PR that implemented an open issue without referencing it. When noticed, close the issue manually with a comment naming the PR (gh issue close N --comment "Implemented by PR #M ...").

Communication

When proposing or reporting a captured issue, include:

• the proposed or created title
• the target repository
• whether it was created in GitHub, imported into nytid, or both
• any duplicate issue found instead of creating a new one

If nothing was recorded, say why.