Filing Bug Reports

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 references/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 N/A — <reason>.
• Available MCP tools: list the MCP tools you have access to
• Relevant source files: read the files involved in the failure

SATK-specific (when Simulink MCP tools are available):

• SATK version: read the VERSION file at the SATK root. If it doesn't exist and a .git/ folder is present, read the latest commit hash and note "development build (<hash>)". If neither exists, ask the user what version of Simulink Agentic Toolkit they are using
• MATLAB: evaluate_matlab_code → disp(version); ver('simulink'); disp(pwd); disp(computer('arch'))
• satk_initialize.m status: evaluate_matlab_code → which('model_read') (empty = not run)
• Connector: evaluate_matlab_code → try; disp(connector.securePort); catch; disp('not running'); end
• MCP config: read .vscode/mcp.json for server mode and binary path

• 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 references/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

• references/bug-report-template.md — The output template (always use this structure)

----

Copyright 2026 The MathWorks, Inc.

----