Skill Usage Audit

Skill Usage Audit

Purpose / When to Activate

Activate:

• Periodically (e.g., after a Discovery session) to verify governance compliance
• Before a release or milestone to audit artefact quality
• When trust in agent compliance needs verification
• On demand by the human (/gaai-status or direct invocation)

This skill enforces Base Rule #2 (Skill-first) by scanning artefacts for the skills_invoked attestation field. It detects artefacts that were produced from cached knowledge without reading the corresponding skill file.

Process

1. Scan all Epic files at contexts/artefacts/epics/*.epic.md (exclude _template.epic.md):

   • Check frontmatter for skills_invoked field
   • If present: verify it includes generate-epics
   • If missing: mark as FAIL

2. Scan all Story files at contexts/artefacts/stories/*.story.md (exclude _template.story.md):

   • Check frontmatter for skills_invoked field
   • If present: verify it includes generate-stories
   • If missing: mark as FAIL
   • Check frontmatter for related_decs field
   • If missing: mark as FAIL (separate from skills_invoked)
   • Check frontmatter for epic field
   • If missing: mark as WARN

3. Produce audit report with:

   • Per-artefact pass/fail status
   • Compliance rate: (passing artefacts / total artefacts) × 100
   • List of non-compliant artefacts for remediation
   • Timestamp of audit

Outputs

Skill Usage Audit Report — {date}

Epics scanned: {count}
Stories scanned: {count}

Non-compliant artefacts:
- {id}: FAIL — missing skills_invoked
- {id}: FAIL — missing related_decs
- {id}: WARN — missing epic field

Compliance rate: {n}/{total} ({pct}%)

Verdict: CLEAN | {n} VIOLATIONS FOUND

Remediation

For each non-compliant artefact, the human or agent must:

1. Read the corresponding skill file (generate-stories/SKILL.md or generate-epics/SKILL.md)
2. Verify the artefact content follows all process steps
3. Add the missing frontmatter fields
4. Commit the fix

This skill does NOT auto-fix artefacts — it reports only. Remediation is a conscious act.

Quality Checks

• Every artefact file in the scan directories is checked (no silent skips)
• Template files (_template.*) are excluded from the scan
• The report clearly distinguishes FAIL (blocking) from WARN (advisory)
• Compliance rate is computed correctly

Non-Goals

This skill must NOT:

• Auto-fix artefacts (report only — remediation is deliberate)
• Check artefact content quality (use validate-artefacts for that)
• Scan non-artefact files (memory, decisions, patterns)