Filing Bug Reports

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

License.p

Audit 0.4.1 · source sha 9090332613b6 · 14 Oct 2026Report an issue or request a re-scan

• Publishermatlab GitHub organizationOwner of the repository this skill is read from
• Source foldermatlab/simulink-agentic-toolkit/skills-catalog/model-based-design-core/filing-bug-reportsThe exact folder we audited
• LicenceNOASSERTIONAs the repository states it
• Commit pinned for this verdict9090332613b6A new audit runs when the source changes
• Repository statusNot archivedLast push 6 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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

1. **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)

2. **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 `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 toolbox status: `evaluate_matlab_code` → `which('model_read')` (empty = toolbox not installed)
   - 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
   - If this is a layout issue and satk status is ok: `evaluate_matlab_code` → `layout.LayoutStateManager.instance().getAnonymizedLayoutSnapshotsPath()` but ask user if they agree to share anonymized layout information first. If you get user permission, do not read the contents of the file at the path returned by getAnonymizedLayoutSnapshotsPath, instead use a tool call to append this very large file directly to the final bug report.

3. **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.

4. **Shrink to a minimal reproduction.** Remove every step, file, and variable that isn't needed to 

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 9090332613b6

Questions about Filing Bug Reports

• github.com/matlab/simulink-agentic-toolkit/tree/main/skills-cata — the audited source at commit 9090332613b6 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology