| name | filing-bug-reports |
| description | Generate a standalone bug report that another developer can use to reproduce, investigate, and fix an issue. Use when the user says 'file a bug', 'write a bug report', 'report this issue', or asks to document a defect for handoff. |
| license | https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md |
| metadata | {"author":"MathWorks","version":"1.3"} |
Filing Bug Reports
Generate a self-contained bug report as a Markdown file that gives a receiving developer everything needed to reproduce the issue — without prescribing root cause or solution.
When to Use
- User asks to file, write, or document a bug
- User wants to hand off a defect for another developer to investigate
- User wants a reproducible record of unexpected behavior
When NOT to Use
- User wants to debug and fix the issue themselves right now — just help them directly
- User wants a design review or code review — use
code-review skill instead
Output Conventions
- File:
issues/BUG-<NNN>-<slug>.md (next available number, kebab-case slug from title)
- Create the
issues/ directory if it doesn't exist
- One bug per file — never combine multiple bugs
Workflow
-
Reconstruct from conversation context. You were present when the bug occurred — use your conversation history to extract:
- What the user was doing (the action and intent)
- What actually happened (error messages, tool output, unexpected behavior)
- What was expected (infer from the user's goal — e.g., if they asked to read a model and got an error, expected behavior is a successful read)
-
Gather environment details programmatically. Don't ask the user for things you can look up:
- Agent workspace root, OS, architecture: from your system context
Skill state vocabulary. The skill spec uses progressive disclosure: metadata (name + description) is always in context; the body loads only when triggered. These terms describe the observable states and are agent-agnostic — they hold for any host that implements the Agent Skills standard, not just Claude Code:
-
Registered — the skill appears in the host agent's available-skills list this session.
-
Described — registered AND has a non-empty description in metadata. (Default state, no glyph.)
-
Name-only (⊘) — registered with only a name; the description field is absent from the agent's registration entry. Record which skills are name-only and stop there. Do not read SKILL.md files on disk to verify whether descriptions exist — the available-skills listing is the only state the bug report records. Reading the source frontmatter is cause-investigation, which is out of scope.
Note: some host agents drop descriptions from the listing automatically when total skill text exceeds an internal budget — for example, Claude Code allocates a character budget that scales with context window size and strips descriptions from least-recently-invoked skills first when the budget is exceeded. Name-only is therefore often expected host behavior in a session with many skills loaded, not a SATK defect. Record the state, but don't frame the bug report as "SATK skill registration is broken" unless the same skill is name-only in a session where the budget clearly isn't exhausted (few skills present, or the host reports no truncation).
-
Invoked (▶) — the skill's body was read into the agent's context this session.
-
Unregistered SATK skill (✗) — a SKILL.md exists on disk under the toolkit's skills-catalog/ but is absent from the available-skills list. ✗ is scoped to SATK only — we don't track unregistered skills from other sources.
With those definitions:
- Skills (stack view): read the available-skills list directly (not prior bug reports or docs) and mark each registered skill per the glossary. For ✗, also consult the SATK skill manifest at the toolkit root and list any SATK skills declared there that aren't in the registered set. Render per the Skills subsection of
assets/bug-report-template.md.
- Skill conflict analysis: only consider SATK
model-based-design-core skills whose bodies are already in your context, and only if you noticed a conflict between them while doing the work that's plausibly related to this bug. Don't re-read skill bodies to hunt for conflicts; if nothing surfaced naturally, write .
-
Reproduce the bug. Re-run the failing operation to confirm it's reproducible and capture exact output. If it passes on retry, note it as intermittent and try to identify what differs.
-
Shrink to a minimal reproduction. Remove every step, file, and variable that isn't needed to trigger the bug. The goal is the smallest input that still fails.
-
Ask the user ONLY for what you cannot determine:
- Expected behavior — only if the output looks plausible but the user says it's wrong (you can't know what "right" looks like)
- Severity / business impact — only if it's ambiguous (an outright crash is obviously high; a formatting nit is obviously low)
- Context from outside this session — if the user references something you didn't witness
-
Write the report using the template in assets/bug-report-template.md. Fill every required section. Mark optional sections N/A if not applicable.
-
Review before saving. Verify:
- A developer unfamiliar with the project can follow the steps without asking questions
- No root cause or fix is prescribed (observations and hypotheses go in the Notes section only)
- Error messages and logs are exact copies, not paraphrased
- The title follows the format:
[Area] — Action — Unexpected result
Guardrails
- Always: Include exact reproduction steps starting from a clean/known state
- Always: Include verbatim error messages and log output (never paraphrase)
- Always: Specify the environment (versions, OS, platform)
- Never: State the root cause — that's the investigator's job
- Never: Propose a fix in the report body (hypotheses go in Notes only, clearly marked as speculation)
- Never: Include secrets, tokens, passwords, or PII — redact with
<REDACTED>
References
assets/bug-report-template.md — The output template (always use this structure)
Copyright 2026 The MathWorks, Inc.
