Skip to content
Skills Library
Programming · Review & audit

polyspace-justify-in-code

/polyspace-justify-in-code

Justifies Polyspace findings by adding annotation comments in the C/C++ source code. Use when the user asks to "add a Polyspace annotation", "justify a finding in the source/in code", "mark as false positive in the code", "suppress a finding with a comment", or wants an in-source justification the next analysis will read. For recording a review status in the results database instead, use polyspace-justify-in-database.

Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Justifies Polyspace findings by adding annotation comments in the C/C++ source code. Use when the user asks to "add a Polyspace annotation", "justify a finding in the source/in code", "mark as false positive in the code", "suppress a finding with a comment", or wants an in-source justification the next analysis will read. For recording a review status in the results database instead, use polyspace-justify-in-database.

Triggers from the description

add a Polyspace annotationjustify a finding in the source/in codemark as false positive in the codesuppress a finding with a comment
Original author description

Justifies Polyspace findings by adding annotation comments in the C/C++ source code. Use when the user asks to "add a Polyspace annotation", "justify a finding in the source/in code", "mark as false positive in the code", "suppress a finding with a comment", or wants an in-source justification the next analysis will read. For recording a review status in the results database instead, use polyspace-justify-in-database.

How it works

  1. When NOT to Use
  2. Annotation syntax
  3. FAMILY:ACRONYM format
  4. Status values
  5. Severity (optional)
  6. Justification text guidelines
  7. User confirmation
  8. Pre-approved justification catalog
  9. Next analysis
Original SKILL.md headings · 116 lines, 776 words
SKILL.md preview
---
name: polyspace-justify-in-code
description: Justifies Polyspace findings by adding annotation comments in the C/C++ source code. Use when the user asks to "add a Polyspace annotation", "justify a finding in the source/in code", "mark as false positive in the code", "suppress a finding with a comment", or wants an in-source justification the next analysis will read. For recording a review status in the results database instead, use polyspace-justify-in-database.
license: MathWorks BSD-3-Clause
metadata:
  version: "1.3"
---
# How to Justify Polyspace Findings

Use Polyspace annotation comments to justify findings that are false positives, intentional behavior, or prevented by external constraints (hardware, protocol, caller validation).

**This skill uses source code comments only.** Do not offer alternative methods (XML files, external config files, etc.). The annotation is always a comment inserted directly in the source code, either on the finding line or as a block around the finding lines.

Recording a review status *in the results database* (Bug Finder `.psbf` or Code Prover `.pscp`, and transferring it across re-runs) is a different mechanism — use `polyspace-justify-in-database` for that. This skill covers only in-source annotations.

## When NOT to Use
- Recording a review status/rationale **in the results database** (`.psbf`/`.pscp`), or carrying reviews across re-runs — use `polyspace-justify-in-database`. That is the other half of the justify pair: this skill writes a comment in the source; `polyspace-justify-in-database` writes a status into the database.
- Deciding *whether* a finding is a real defect or acceptable in the first place — review it first (`polyspace-review-findings` for Bug Finder / as-you-code findings, `triage-orange-checks` for Code Prover oranges).
- Fixing a real error in the code — use `polyspace-fix-findings`.

## Annotation syntax

### Line mode (default)

Insert at the end of the finding line:

```c
code_on_finding_line; /* polyspace FAMILY:ACRONYM [Status] "justification text" */
```

### Block mode

Insert around the finding lines:

```c
/* polyspace-begin FAMILY:ACRONYM [Status] "justification text" */
code_on_finding_lines;
/* polyspace-end FAMILY:ACRONYM */
```

## FAMILY:ACRONYM format

`FAMILY` is the **annotation** family name, which for coding standards is *not* the family
string the results carry: a rule the results report under family `MISRA C:2023` is annotated
as `MISRA-C-2023`, and a MISRA C 2012 rule is annotated as `MISRA-C3`. Take the acronym / rule
number from the results, but take the family from this list:

- `Defect:INT_ZERO_DIV` — Bug Finder defect (family `Defect`, same as in the results)
- `MISRA-C3:8.4` — MISRA C 2012 rule
- `MISRA-C-2023:8.4` — MISRA C 2023 rule (the results spell this family `MISRA C:2023`)
- `CERT-C:DCL00-C` — CERT C rule
- `CWE:119` — CWE weakness

The acronym also needs stripping. For a coding-rule finding the results repeat the standard inside
the check identifier itself — the check reads as the standard followed by the rule number, e.g. a
2012 rule 8.4 is reported as `MISRA C:2012 8.4` and a directive as `MISRA C:2012 D4.6`. Only the
last part, the rule number, belongs after the colon: `MISRA-C3:8.4`, never
`MISRA-C3:MISRA C:2012 8.4`. Bug Finder defect acronyms carry no such prefix and are used as-is.

Do not guess a family name and do not copy the results family verbatim for a coding standard.
If the standard you need is not listed above, look the annotation family up in the Polyspace
annotation documentation (invoke `polyspace-find-option-documentation` for the annotation page)
rather than inventing one.

## Status values

- `Justified` (default)
- `Not a defect`
- `No action planned`

## Severity (optional)

Append severity after the status with a colon:

```c
/* polyspace FAMILY:ACRONYM [Justified:High] "justification text" */
```

Values: `High`, `Medium`, `Low`.

## Justification text guidelines

A good justification explains **why** the deviation is acceptable. Include:
- The **reason** for the deviation (e.g., hardware access, portability, performance, adopted code that cannot be modified, code quality, project convention)
- **Specific details** — reference the relevant function, variable, constraint, or platform

Keep it concise (under 20 words), no trailing period. Examples:
- `"Hardware register read requires cast to uint32_t"`
- `"Vendor-supplied HAL library cannot be modified"`
- `"Inline assembly required for cycle-critical ISR"`
- `"int is 32-bit on all target platforms for this project"`
- `"Helper macro reduces repetition across 12 call sites"`
- `"Denominator checked non-zero by caller validate_input()"`

## User confirmation

**Always ask the user for confirmation before inserting the annotation.** Present:
1. The finding (family, acronym, message, location)
2. Your proposed justification text
3. The exact annotation you plan to insert

Wait for explicit approval before editing the file.

## Pre-approved justification catalog

If the project has a justification catalog JSON file:

**If the `query_justification_catalog` tool is available**, use it with the `findings` and `catalog_file_path` arguments to get pre-approved justification texts.

**Otherwise**, invoke the `polyspace-query-justification-catalog` skill, or if skills are not available, read `polyspace-query-justification-catalog/SKILL.md` in this skill's parent folder for the catalog JSON schema and how to query it directly.

If no catalog file is provided and the project has IDE markers (`.vscode/`, `.project`, `.vs/`), the user may have a justification catalog configured in the IDE extension settings — ask them.

## Next analysis

On the next Polyspace analysis run, the annotation is recognized and the finding is marked as justified.

---

Copyright 2026 The MathWorks, Inc.

---
Files in this package (2)
  • SKILL.md 6 KB
  • manifest.yaml 1 KB

Versions

The database has no other skills named polyspace-justify-in-code.

Database snapshot: 13.11.2026 · package version a6f3d2358536 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100polyspace-justify-in-database
    Records a review status and rationale on Polyspace findings directly in the results database (.psbf for Bug Finder, .pscp for Code Prover) and carries that review across re-runs. Use when the user asks to "set the status to Justified", "mark this as acceptable in the results",…
  • 90polyspace-fix-findings
    Fixes or justifies Polyspace findings after analysis. Use when the user asks to "fix this finding", "fix these defects", "fix violations", "address Polyspace results", or wants to resolve static analysis findings.
  • 100annotation
    This skill should be used when the user says "find annotations", "list audit tags", "show @audit comments", "compile annotations", "/annotation", "find todos", "find audit comments", "what did I annotate", "annotation summary", "list audit findings", "what's annotated", or wants…
  • 100code-comments
    Write, review, or remove code comments. Use when adding comments or doc comments, reviewing the comments in a diff, or cleaning up or removing comments.
  • 100wise-code-comments
    Code-comment rules for EVERY comment and docstring written on the user's behalf in ANY programming language. ALWAYS consult this skill before writing, rewriting, or reviewing a code comment, docstring, or inline annotation - whether adding comments to new code, editing code that…
  • 100ro-source-modification
    Modify rAthena C++ server source safely - justify the change, isolate custom code, compile, test, and keep upstream merges possible. Use when the user says "change the source", "new script command", "new status effect", "change skill formula", "add a battle config option",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.