---
name: jgs-v1-audit
description: |
  JGS Model Audit — free, read-only SysML model health audit. Surfaces structural and methodology
  findings with element-ID links, severity grades, and a data-driven Engagement Brief.

  Invocation: /jgs-v1-audit [<root-package-qn-or-id>]

  Requires the JGS MCP bridge (v1 or v2) running on LicenceTier.FREE or higher.
  Makes no writes to the model.

  Use when: auditing a SysML model for naming, documentation, requirement, duplicate, unused-type,
  or methodology issues. The report ends with an Engagement Brief listing JGS-FIXABLE findings
  and a contact CTA.
---
<!--
Copyright (c) 2026 JG Systems Consulting Ltd. All Rights Reserved.
See LICENSE for terms.
-->

# JGS Model Audit

## When to use

Use when you want a full model-health audit: the orchestrator runs the six audit specialists and consolidates their severity-graded findings into one report.

## Prerequisites

- The `jgs-magic-sysmlv1-mcp` bridge installed and reachable (the FREE/read-only tier is sufficient).
- A SysML v1 project open in CATIA Magic / MSOSA.

- Optional: a root package ID to scope the audit (otherwise the whole model is audited).
You are the orchestrator for the `jgs-v1-audit` skill bundle. You coordinate six specialist
audit sub-skills, merge their findings, and produce a structured report.

**This skill makes no writes to the model.**

---

## Phase 1: Pre-flight

### Step 1.1 — Ping the bridge

Call `mcp__jgs-sysmlv1__ping({})`. If this fails, try `mcp__jgs-sysmlv2__ping({})`.

If both fail:
```
ERROR: JGS MCP bridge is not reachable. Ensure the bridge plugin is running in CATIA Magic
Systems of Systems Architect (MSOSA) and that an MCP server entry for jgs-sysmlv1 or
jgs-sysmlv2 is configured in .mcp.json.
```
Stop.

From the ping response, extract:
- `bridge_adapter` (default `"sysml-v1"` if absent)
- `bridge_version` (default `"unknown"` if absent)
- Project name (from `project_name` field or `"Unknown Project"` if absent)

### Step 1.2 — Resolve root package

If the user provided an argument to `/jgs-v1-audit`, use it as the root package ID directly.

Otherwise call:
```
mcp__jgs-sysmlv1__get_root_package({})
```
(or `mcp__jgs-sysmlv2__get_root_package({})` if v2 bridge detected)

If the response contains multiple top-level packages, list them and ask the user to select one before proceeding.

If no root package is found, print:
```
ERROR: No root package found in the model. Ensure a SysML model is open in MSOSA.
```
Stop.

Store: `root_package_id`, `project_name`, `bridge_adapter`, `bridge_version`.

### Step 1.3 — Validate specialist presence

The six required specialist directories are:
- `jgs-v1-audit-naming`
- `jgs-v1-audit-docs`
- `jgs-v1-audit-requirements`
- `jgs-v1-audit-duplicates`
- `jgs-v1-audit-unused`
- `jgs-v1-audit-methodology`

Check that each directory exists under the `jgs-v1-audit/` folder alongside this `SKILL.md`.
For each missing specialist, create a system finding:

```json
{
  "check_id": "SYS-003",
  "severity": "CRITICAL",
  "domain": "system",
  "title": "Required specialist not found: <name>",
  "detail": "The specialist skill directory '<name>' is missing from the jgs-v1-audit bundle. Reinstall the full bundle from the JGS distribution.",
  "element_id": null,
  "element_qn": null,
  "requires_write_access": false,
  "requires_jgs_skills": false
}
```

If any specialists are missing:
1. Assign IDs to the SYS-003 findings (format `AUDIT-SYS-001`, `AUDIT-SYS-002`, etc.)
2. Write a stub report containing only those findings (see Report Format below)
3. Print the terminal summary showing only those findings
4. Stop — do not proceed to Phase 2

---

## Phase 1.5: Native validation (validate_model)

Run CATIA Magic's own validation engine as an authoritative pre-pass, before the heuristic specialists.

Call `mcp__jgs-sysmlv1__validate_model({})` — **no arguments** (model-wide; cannot be scoped).

`validate_model` can return tens of thousands of characters on a real model (~88 KB observed). Do **not**
embed the raw result. Summarize: the total violation count plus a breakdown by severity/rule, and keep at
most **25 representative** violations (with element IDs) for the report's Native Validation section. Store
`native_validation_count` (the true total) and the capped list. If the call errors, set
`native_validation_count` to `"unavailable"` and note it — do **not** abort the audit.

This is the host tool's own verdict (not a heuristic) and leads the report: "CATIA Magic's validator
reported N issues before the JGS heuristic checks ran."

---

## Phase 2: Dispatch Specialists

Dispatch all six specialist sub-skills in parallel using the Agent tool. Pass each:
- The `root_package_id` as the primary argument
- The `bridge_adapter` value as context

Specialist invocations:
- `/jgs-v1-audit-naming <root_package_id>`
- `/jgs-v1-audit-docs <root_package_id>`
- `/jgs-v1-audit-requirements <root_package_id>`
- `/jgs-v1-audit-duplicates <root_package_id>`
- `/jgs-v1-audit-unused <root_package_id>` (with bridge_adapter context)
- `/jgs-v1-audit-methodology <root_package_id>` (with bridge_adapter context)

Each specialist returns a JSON array of findings (without `id` or `jgs_fixable` fields).

If a specialist fails to return valid JSON, emit a SYS-001 finding for it and continue.

---

## Phase 3: Merge, Dedup, Assign IDs

### Step 3.1 — Collect all findings

Combine all finding arrays from all specialists into one pool. Each finding has `check_id`, `severity`, `domain`, `title`, `detail`, `element_id`, `element_qn`, `requires_write_access`, `requires_jgs_skills`.

### Step 3.2 — Deduplicate

Dedup key: `(element_id ?? hash(detail), check_id)`

- If two findings have the same `check_id` and the same non-null `element_id`, they are duplicates — keep the first.
- If two findings have `element_id: null` and the same `check_id` and the same `detail` (trimmed), they are duplicates — keep the first.
- Cross-domain collisions cannot occur because each domain uses a distinct `check_id` prefix (NM, DC, RQ, DU, UN, MT, SYS).

### Step 3.3 — Derive `jgs_fixable`

For each surviving finding:
```
jgs_fixable = requires_write_access OR requires_jgs_skills
```

### Step 3.4 — Assign `id`

Assign `id` after deduplication. NNN increments per domain across post-dedup survivors only (contiguous within each domain):

- `AUDIT-NM-001`, `AUDIT-NM-002`, … for naming findings
- `AUDIT-DC-001`, `AUDIT-DC-002`, … for docs findings
- `AUDIT-RQ-001`, … for requirements findings
- `AUDIT-DU-001`, … for duplicates findings
- `AUDIT-UN-001`, … for unused findings
- `AUDIT-MT-001`, … for methodology findings
- `AUDIT-SYS-001`, … for system findings

### Step 3.5 — Sort

Sort all findings by: severity order (CRITICAL → MAJOR → MINOR → INFO), then by `id`.

---

## Phase 4: Write Report

### Step 4.0 — Emit findings JSON (handoff for jgs-v1-fixplan)

Also write the merged, deduped finding pool (the same findings going into the report) as
`jgs-audit-findings-YYYY-MM-DD.json` — a JSON array of the finding objects plus `project_name`,
`bridge_adapter`, and `root_package_id`. This is the machine-readable handoff that `/jgs-v1-fixplan`
consumes (it never parses the markdown report). No extra tool calls — it serialises the pool already built
in Phase 3.

### Step 4.1 — Determine output filename

Base name: `jgs-audit-report-YYYY-MM-DD.md` (today's date).

If a file with that name already exists in CWD, append a counter:
- `jgs-audit-report-YYYY-MM-DD-2.md`
- `jgs-audit-report-YYYY-MM-DD-3.md`
- etc.

Use the first available name.

### Step 4.2 — Compute counts

```
critical_count = count of findings where severity == "CRITICAL"
major_count    = count of findings where severity == "MAJOR"
minor_count    = count of findings where severity == "MINOR"
info_count     = count of findings where severity == "INFO"
jgs_fixable_count = count of findings where jgs_fixable == true
```

### Step 4.3 — Compute model stats

Call:
```
mcp__jgs-sysmlv1__get_model_metrics({})
```

`get_model_metrics` takes **no arguments** and returns whole-model counts (it cannot be scoped to a
package). Extract `element_count`, `diagram_count`, `requirement_count`. Use 0 if the call fails.
If the audit was scoped to a sub-package, note in the report that these model stats are model-wide.

### Step 4.4 — Write the markdown report

Write to the chosen filename. The report structure:

```
# JGS Model Audit Report

**Project:** <project_name>  **Date:** YYYY-MM-DD  **Bridge version:** <bridge_version>

## Executive Summary

| Severity | Count |
|---|---|
| CRITICAL | <critical_count> |
| MAJOR | <major_count> |
| MINOR | <minor_count> |
| INFO | <info_count> |
| **JGS-FIXABLE** | **<jgs_fixable_count>** |

**Model stats:** <element_count> elements · <diagram_count> diagrams · <requirement_count> requirements

**Native validation (validate_model):** <native_validation_count> rule violation(s) reported by CATIA
Magic's own validator (model-wide), before the JGS heuristic checks. See Native Validation section below.

## Native Validation

Summary of `validate_model` (Phase 1.5): total = <native_validation_count>, by severity/rule:
<one line per severity/rule with counts>. Up to 25 representative violations (element-ID linked):
<capped list, or "validator output unavailable">.

## Findings

### CRITICAL

For each CRITICAL finding, emit:

#### [<id>] <title>

**Element:** `<element_id>` — `<element_qn>`
(omit the Element line if element_id is null — model-wide finding)

**Detail:** <detail>

If jgs_fixable is true, add: **Tag:** `[JGS-FIXABLE]`

---

### MAJOR

(same structure as CRITICAL)

### MINOR

(same structure)

### INFO

(same structure)

## Methodology Assessment

Collect all MT-* findings and produce a prose summary: which layers were found/missing,
whether requirements are grounded, orphan count, allocation status, interface gaps, stub count.
Begin with the MT-000 heuristic disclaimer.
```

### Step 4.5 — Compute effort tier breakdown

For each JGS-FIXABLE finding, assign an effort tier using this lookup (specific check_id row first, then domain wildcard, then Moderate default):

| check_id | Tier |
|---|---|
| MT-001 | Complex |
| MT-002 | Moderate |
| MT-003 | Quick-win |
| MT-004 | Moderate |
| MT-005 | Moderate |
| MT-006 | Quick-win |
| NM-* | Quick-win |
| DC-* | Quick-win |
| DU-* | Quick-win |
| UN-* | Quick-win |
| RQ-* | Moderate |
| (default) | Moderate |

Count: `quick_win_count`, `moderate_count`, `complex_count`.

---

## Phase 5: Generate Engagement Brief

Append to the report file:

```
## Engagement Brief

### Risk Summary

One paragraph calibrated to finding distribution:
- If CRITICAL > 0: "This model has <critical_count> critical finding(s) indicating fundamental SE principle violations. Without resolution, downstream reviews and programme milestones are at risk. Immediate attention is recommended."
- If CRITICAL == 0 and MAJOR > 0: "This model is structurally sound at the critical level but has <major_count> significant gaps that will likely cause traceability failures or review challenges if left unaddressed."
- If CRITICAL == 0 and MAJOR == 0: "This model is in good structural health with <minor_count> quality improvements recommended. These are generally quick to resolve and will reduce maintenance burden."

### Fix Complexity Estimate

<jgs_fixable_count> JGS-FIXABLE finding(s) identified:

| Tier | Count | Description |
|---|---|---|
| Quick-win | <quick_win_count> | Addressable in a single session with write-enabled MCP |
| Moderate | <moderate_count> | Requires structural changes or traceability additions |
| Complex | <complex_count> | Requires methodology rework or governance setup |

### What a JGS Engagement Delivers

- Automated fixes for all quick-win and moderate JGS-FIXABLE findings via write-enabled MCP
- Proprietary methodology skills for SE layer compliance and requirement traceability
- Model governance setup (naming conventions, documentation standards, review checklists)
- Post-fix re-audit to confirm resolution

### Call to Action

Contact JG Systems Consulting Ltd. — <support@jgsystemsconsulting.com>
Most quick-win and moderate JGS-FIXABLE findings in this report can be resolved in a single JGS session.
Complex findings (e.g. SE layer restructure) require a scoped methodology engagement.
```

---

## Phase 6: Terminal Summary

Print to the terminal:

```
JGS Model Audit — <project_name> — YYYY-MM-DD
═══════════════════════════════════════════════
  CRITICAL    <critical_count>
  MAJOR       <major_count>
  MINOR       <minor_count>
  INFO        <info_count>
───────────────────────────────────────────────
  JGS-FIXABLE <jgs_fixable_count>   (require write access or proprietary skills)

Full report: <output_filename>
```

Done.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Passing arguments to `validate_model` / `get_model_metrics` | Both take no arguments and are model-wide — pass `{}`; they cannot be scoped to a package |
| Embedding the full `validate_model` output in the report | It can exceed tens of thousands of characters (~88 KB observed) — summarize by severity/rule, do not inline the raw list |
| Dispatching specialists sequentially | Dispatch all six in parallel via the Agent tool; if one returns invalid JSON, emit a SYS-001 finding and continue rather than aborting the audit |
| Aborting when only the v1 bridge answers `ping` | Fall back to `mcp__jgs-sysmlv2__ping` and the `v2` tool variants only if v1 is unreachable — the audit runs against whichever bridge responds |