| 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 |
File issue
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.
When to file
| 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) |
Workflow
- [ ] 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.
Frontmatter
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.
Closure
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.
Homelab constraints
- Non-shipping by design: this skill never commits/pushes (ledger edits
only). Ship the issue file via
draft-commit when authorized.
- Never put secrets or credential material in issue bodies.
- Never cluster-mutate as part of filing (
kubectl apply, flux reconcile,
mutating MCP, etc.).
