filing-fleetlens-issues

name	filing-fleetlens-issues
description	Use when the user asks to file, log, track, open, or backlog a GitHub issue for a Fleetlens enhancement, bug, or chore. Applies when capturing work for future handoff to an implementation agent rather than doing it inline in the current session.

Filing Fleetlens Issues

Overview

Issues in cowcow02/fleetlens are written to be agent-ready: a subagent or future Codex session should be able to pick one up and ship it without a follow-up conversation. This skill enforces a consistent structure and label taxonomy so the roadmap stays legible and handoffs are clean.

When to Use

• User says "file an issue", "log this", "create a ticket", "add to backlog", "let's track this", "we should eventually do X"
• Capturing work for asynchronous / future execution
• Converting a chat idea into a trackable roadmap item

When NOT to Use

• Micro-fixes you can finish in the current session — just do them
• Exploratory "what if" discussion — confirm user intent before filing
• Conversation-scoped TODOs — use TodoWrite instead

Issue Body Template

Every issue body MUST have all four sections. Omit any and it stops being agent-ready.

## Why
<1–2 lines: motivation, user value, or signal that prompted this>

## Scope
<files / packages touched — parser / web / cli / daemon — with paths if known>

## Acceptance
- [ ] <testable criterion>
- [ ] <testable criterion>

## Out of scope
- <explicit exclusion to prevent drift>

Title Rules

• Verb-first, lowercase, scope-named: add rule-based insights panel to dashboard
• ≤ 70 characters
• No trailing period
• Avoid adjectives ("better", "nicer") — state the concrete change

Labels

Always apply one type:*, at least one area:*, and one size:*. Add agent-ready only if the spec is tight enough for an implementation agent to finish unsupervised — if in doubt, leave it off.

Label group	Values
type:*	feat, fix, chore, docs
area:*	parser, web, cli, daemon
size:*	s (<1hr), m (half day), l (multi-session, usually needs a plan first)
flag	agent-ready (optional; reserve for s/m)

Command

gh issue create \
  --title "add rule-based insights panel to dashboard" \
  --body "$(cat <<'EOF'
## Why
One-line motivation.

## Scope
- path/to/file.ts
- another/path.tsx

## Acceptance
- [ ] criterion 1
- [ ] criterion 2

## Out of scope
- explicit exclusion
EOF
)" \
  --label "type:feat,area:parser,area:web,size:m,agent-ready"

After filing, print the URL gh returns so the user can click through.

Common Mistakes

• Vague acceptance criteria ("make it nicer", "improve UX") — rewrite until a machine could check pass/fail
• Missing "Out of scope" — without it agents drift into adjacent refactors
• Bundling multiple concerns — split into separate issues before filing
• agent-ready on size:l — l almost always needs a written plan first; strip the label
• Raw paste of a chat idea — always translate into the four-section template, even if the chat already covered the same points
• Titles starting with nouns ("Dashboard insights") — rewrite verb-first ("add dashboard insights")

Red Flags — Stop and Reconsider

• You're about to use "improve", "better", "refactor X" with no acceptance criteria → not agent-ready
• The Scope section lists >5 files across >2 packages → probably needs splitting
• You can't think of anything to put in "Out of scope" → you haven't scoped it enough