Menu
Create or update local issues under docs/issues/; use when filing a gap out of scope for the current change.
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/Apocrathia/homelab --skill file-issueThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Based on SOC occupation classification
Showing SKILL.md
| name | file-issue |
| description | Create or update local issues under docs/issues/; use when filing a gap out of scope for the current change. |
| disable-model-invocation | true |
Record a problem or desired state under docs/issues/.
Issues define what; plans define how. Plans live under
docs/plans/ (and optionally
.cursor/plans/ for IDE-only sessions) via
project-planner. Do not invent a
plan in the issue body.
Do not create GitLab issues unless the operator explicitly asks. Local
docs/issues/ is the default backlog.
Question channel when acceptance is fuzzy:
.agents/context/questions.md.
| Situation | Action |
|---|---|
| Fixable in the current change | Fix it — no issue |
| Out of scope for current change | File (or update duplicate) |
| Duplicate of an existing open issue | Update that file |
| Feature / spec / multi-path bug; acceptance unclear | alignment first, then file |
| Single intentional shortcut | ponytail: in code, not here |
Clustered ponytail: debt (a theme) | File one issue for the theme |
| Architecture friction | architecture-review then file (kind: architecture) |
- [ ] 1. Search docs/issues/*.md for duplicates (skip README, _template)
- [ ] 2. Duplicate → update that file; skip to step 5
- [ ] 3. Else copy docs/issues/_template.md → docs/issues/<short-slug>.md
- [ ] 4. Fill frontmatter + body (include Feedback loop)
- [ ] 5. Report the path to the operator
Template: docs/issues/_template.md.
Conventions: docs/issues/README.md.
Match docs/issues/_template.md:
| Field | Notes |
|---|---|
title | Short title |
kind | bug | feature | spec | architecture |
status | open | in-flight | blocked | closed | wontfix | superseded | promoted |
severity | blocker | high | medium | low |
source | e.g. agent | human | dogfood | review | alert | flux | ci |
found_at | YYYY-MM-DD |
found_by | Optional |
area | e.g. flux | helm | talos | observability | security | apps | networking | storage | agents |
slice | Optional: afk | hitl |
plan | Optional path (docs/plans/… preferred; .cursor/plans/… for IDE-only) |
gitlab | Optional URL when operator-promoted |
branch | Optional when in-flight |
Body must include Feedback loop (how to know acceptance is met without reading the full diff). Bugs: repro encouraged, not mandatory.
When acceptance is met, delete docs/issues/<slug>.md in the same change
set as the fix, and fix backlinks in linked plans/docs.
Closure is owned by reconcile-docs on the ship
path (or the parent/operator if that skill is not in play). Do not leave
satisfied issue files around.
draft-commit when authorized.kubectl apply, flux reconcile,
mutating MCP, etc.).