Skill Diagnostics

skill-diagnostics

Purpose

Perform a static audit of an AL workspace against the project's copilot-instructions.md contract. Produce a structured report of findings. Report only. Never modify source code. Never invent rules that are not declared in the contract.

When to load

Load this skill when the user asks you to:

• Audit the workspace / run a compliance check / scan for issues
• Review the code before a PR / before a release
• Diagnose why a new file does not match project conventions
• List all violations of the copilot-instructions.md contract
• Generate a contract-drift report

Input expectations

• Repository contains .github/copilot-instructions.md (required · if missing, emit a Blocker finding and continue with a reduced rule set)
• Workspace contains one or more AL projects with app.json
• Optional: test folder(s) declared in AL-Go settings.json under testFolders

Finding classes

Group every finding into exactly one of four classes:

Severity scale

If in doubt between two levels, downgrade. A noisy Blocker-heavy report erodes trust. Reserve Blocker for things that would fail review hard.

Rule catalogue · the ~20 rules this skill checks

Rules map 1:1 to statements in copilot-instructions.md. If a rule is not declared in the contract, do not check it.

Compliance (7 rules)

Code quality (8 rules)

Test coverage (2 rules)

Permissions (3 rules)

Workflow

Follow these steps in order.

Step 1 · Verify contract presence

• Check that .github/copilot-instructions.md exists
• If missing: emit finding [Blocker · Compliance] No copilot-instructions.md found — running with reduced rule set
• Parse the contract and extract which rules are declared. Only check rules that are declared.

Step 2 · Enumerate AL objects

• Read every *.al file in the declared appFolders from .AL-Go/settings.json (or app/ by default)
• For each file, extract object type, ID, name, declared properties, fields, procedures

Step 3 · Apply the rule catalogue

• For every object, run the rules in the catalogue above
• Record each violation as a finding with these fields:
  • id (e.g. C3, Q1)
  • severity (Blocker, Major, Minor, Nit)
  • class (Compliance, Code quality, Test coverage, Permissions)
  • message (short human-readable description)
  • file (relative path)
  • line (starting line number)
  • remediation (one-sentence suggestion · never code)
  • contract_source (which section of the contract backs this rule)

Step 4 · Aggregate and prioritize

• Group findings by class
• Within each class, sort by severity (Blocker → Major → Minor → Nit)
• Within severity, sort by file path then line number

Step 5 · Emit the report

Use the output format below. Stick to it exactly.

Output format

# skill-diagnostics · audit report

**Scanned:** <N> files · <M> objects
**Contract:** `.github/copilot-instructions.md` (<rules_declared>/<rules_catalogue> rules active)

## Summary

- **Blocker:** <n1>
- **Major:**   <n2>
- **Minor:**   <n3>
- **Nit:**     <n4>

## Findings

### Compliance (<count>)

- **[C3 · Blocker]** Table `CEB Sample Table` missing `DataClassification`
  at object level
  - `app/src/Tables/CEBSampleTable.Table.al:7`
  - *Remediation*: add `DataClassification = CustomerContent;` at object level
  - *Rule source*: `copilot-instructions.md` → "Required Patterns · Tables"

### Code quality (<count>)

- ...

### Test coverage (<count>)

- ...

### Permissions (<count>)

- ...

## Skills Applied

| Rule IDs checked | Count | Source |
|---|---|---|
| C1, C2, C3, C4, C5, C6, C7 | 7 | copilot-instructions.md → "Required Patterns · Tables / Pages / Enums" |
| Q1, Q2, Q3, Q4, Q5, Q6, Q7, Q8 | 8 | copilot-instructions.md → "Required Patterns · Codeunits" + "Prohibited" + "Style" |
| T1, T2 | 2 | copilot-instructions.md → "Test Coverage" |
| P1, P2, P3 | 3 | copilot-instructions.md → "Permissions" |

Rules skipped because not declared in contract: <list or "none">

Constraints

• NEVER modifies code. This skill only reports. If the user asks for automatic fixes, politely decline and point them to skill-fix (if available) or manual remediation.
• NEVER invents rules. If a rule sounds reasonable but is not declared in the contract, do not apply it. Instead, list it in a separate section called "Suggested contract additions" at the end of the report.
• NEVER aggregates severities into a single "score". Findings are qualitative · a single Blocker matters more than ten Nits.
• Report is idempotent. Running the skill twice on the same workspace produces the same output.
• Findings cite file:line. Every finding must be traceable to a specific location in the source.

References

• Agent Skills specification: https://agentskills.io/specification
• Workshop Bloque 02 material: https://javiarmesto.github.io/workshop-v-valley-aldc-2026-04/bloques/02-aldc/
• Project contract: .github/copilot-instructions.md (sibling file)

Example invocations

Any of these trigger this skill via Copilot's auto-match on the description:

• "Audit my workspace for compliance issues"
• "Run a diagnostics scan before I open the PR"
• "Check which objects violate the project contract"
• "Give me a list of Blocker findings in this repo"
• "Scan for missing tooltips in the tables"

Explicit invocation also works:

Load skill-diagnostics and scan the workspace. Use the output format strictly
and include the Skills Applied block at the end.