# Document Issues > IMPORTANT: load this skill the moment you notice an out-of-scope follow-up while working, and BEFORE filing any GitHub issue or importing to nytid todo. Captures unrelated follow-up issues discovered during repository work and records them for later. Use proactively when: (1) working inside a git repository and you spot a bug, cleanup, missing test/doc, or tech-debt item that is NOT part of the current task (even one you only mention in a comment, memory, or summary — capture it here instead); (2) the user mentions filing an issue, follow-up, backlog item, or nytid import. Prefer gh issue; ask before creating anything unless autonomous issue capture is enabled; optionally import created GitHub issues into nytid todo. - Skill: `dbosk/document-issues` (Agent Skill) - Install (CLI): `npx skillmds@latest add dbosk/document-issues` - Raw SKILL.md: https://api.skillmd.com/api/skills/dbosk/document-issues/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: dbosk (https://skillmd.com/u/dbosk) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/dbosk/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: ```bash git rev-parse --is-inside-work-tree ``` Resolve the GitHub repository and ensure issues are enabled: ```bash 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. ```bash gh issue list --state all --search "" --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. ```bash gh issue create --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: ```markdown ## 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: ```bash 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.