| name | phase-fails |
| description | Phase guidance for the neuroflow /fails command. Orients agent approach for logging user dissatisfaction, categorising complaints accurately, and preparing GitHub issue reports. |
phase-fails
The /fails command is a dissatisfaction capture utility. Its job is to listen without defending, categorise accurately, and make it frictionless for the user to report problems upstream.
Approach
- Listen to the user's complaint in full before categorising — do not interrupt or redirect
- Route to the correct file without minimising or reframing the complaint
- If the user is frustrated, acknowledge it briefly before asking clarifying questions
- When the category is ambiguous, ask rather than guess
- Do not offer fixes or workarounds during
/fails — record the problem as stated; fixes belong in a follow-up conversation
Categories
core.md — Plugin behaviour
Problems with how neuroflow itself behaves:
- A phase ran unexpectedly (skipped steps, looped, produced nothing)
- Files were saved in the wrong place, renamed, or deleted
- A command ignored a user instruction or contradicted a previous decision
- Project state was corrupted or inconsistent after a command completed
science.md — Scientific quality
Problems with the scientific work produced:
- A paper retrieved was irrelevant, retracted, or misrepresented
- An analysis ran on wrong data, in the wrong direction, or violated method assumptions (e.g. ICA on a transposed matrix)
- A figure has wrong axis labels, wrong units, or misleading presentation
- A statistical test was inappropriate for the data type or design
- Preprocessing steps were applied out of order or incorrectly
ux.md — Interaction quality
Problems with how the interaction felt:
- Prompts were confusing or asked for the same information twice
- Output was too verbose, too sparse, or poorly formatted
- The suggested next step was irrelevant or wrong for the context
- The conversation felt circular or didn't progress
- The command asked too many questions before doing useful work
GitHub reporting
After logging a fail, always ask whether the user wants to report it as a GitHub issue. Most users won't — but asking takes one second and gives the plugin a direct feedback channel.
When composing the issue:
- Use the category tag in brackets in the title:
[core], [science], or [ux]
- Keep the description factual and specific — avoid emotive language
- Include the plugin version if available in
project_config.md
- URL-encode the title and body using Node.js (
node -e "process.stdout.write(encodeURIComponent('...'))") — probe once; if unavailable, encode manually (space→%20, newline→%0A, #→%23, &→%26, =→%3D, ?→%3F, +→%2B, /→%2F, :→%3A). Never use gh CLI — it requires authentication and is not needed here.
- Open the URL using
open (macOS/Linux) or start "" "<url>" (Windows) rather than presenting it as text — the user should be one click from submitting
- If the browser open fails, print the full URL so the user can paste it manually
Relevant skills
neuroflow:neuroflow-core — read first; defines the command lifecycle and .neuroflow/ write rules
Slash command
/neuroflow:fails — runs this workflow as a slash command.
