file-issue
npx machina-cli add skill rjroy/vibe-garden/file-issue --openclawFile Issue
Write a structured issue to .lore/issues/ directly from an observation.
When to Use
- You spotted a bug, gap, or inconsistency during other work
- The user asks you to record something as an issue
- Something is worth tracking but isn't the current task
This bypasses the idea: capture and /review-ideas refinement flow. Use it when the observation is already clear enough to write up.
Process
- Determine the issue from context (working context, user request, or both)
- Write the issue file to
.lore/issues/[kebab-case-title].md - Report what was filed and the path
No conversation loop. No interactive refinement. If the observation is too vague to write up, say so and suggest using idea: to capture it for later refinement with /review-ideas.
Output
Save to .lore/issues/[kebab-case-title].md
Before writing: Load ${CLAUDE_PLUGIN_ROOT}/shared/frontmatter-schema.md to get frontmatter field definitions and status values for issues.
Document Structure
---
[frontmatter per schema, status: open]
---
# [Issue Title]
## What Happened
[Description of the observation]
## Why It Matters
[Impact or consequence]
## Fix Direction
[Suggested approach, if known. Omit section if no direction is clear.]
Frontmatter Tips
- title: Name the problem, not the symptom (e.g., "Stale cache after config reload" not "Config changes don't apply")
- tags: Include problem type (bug, gap, inconsistency, debt), domain, and technology
- modules: Match codebase directory structure where possible
- related: Link to the lore artifact where you noticed the issue, if applicable
Constraints
- Create the
.lore/issues/directory if it doesn't exist - Use today's date for the
datefield - Always set
status: open - Omit
modulesandrelatedwhen they don't apply (methodology or process issues) - Omit "Fix Direction" section entirely if no direction is known, rather than writing a vague placeholder
- Don't work the issue. File it and move on.
Source
git clone https://github.com/rjroy/vibe-garden/blob/main/lore-development/skills/file-issue/SKILL.mdView on GitHub Overview
File Issue creates a structured issue in .lore/issues from an observation made during work. It enables recording bugs, gaps, or patterns directly, bypassing the idea capture flow for faster traceability and consistent record-keeping.
How This Skill Works
From the observed context, determine the issue. Write the issue to .lore/issues/[kebab-case-title].md with the standard frontmatter and a body including What Happened, Why It Matters, and (if known) Fix Direction. The frontmatter should follow the schema, include today's date, and set status to open. No conversation loop; if the observation is too vague to write up, indicate that and suggest using idea: for later refinement with /review-ideas.
When to Use It
- You spotted a bug, gap, or inconsistency during other work
- The user asks you to record something as an issue
- Something is worth tracking but isn't the current task
- You want to bypass idea capture and file the issue directly
- The observation is clear enough to write up and track immediately
Quick Start
- Step 1: Observe and determine the issue context
- Step 2: Write the issue to .lore/issues/[kebab-case-title].md with frontmatter and body
- Step 3: Report the file path and keep status as open
Best Practices
- Write a clear kebab-case title that names the problem, not the symptom
- Tag the issue with type (bug, gap, inconsistency, debt), plus domain and technology
- Match the modules field to the codebase directory structure when possible
- Link to the lore artifact where you noticed the issue, if applicable
- Set date to today and status to open; omit modules/related if not applicable
Example Use Cases
- Stale cache after config reload in the authentication module
- Missing input validation on the signup form
- Inconsistent API response times under load
- Gap: need clearer logging around data export
- Debt: obsolete feature-flag docs still present
