Business Compliance

Run a fully autonomous domain compliance audit on a page or component of the Hexagone Web application. The skill discovers documented business rules in

docs/domain/

, extracts the entities and bounded context of the target screen, matches applicable rules, detects violations of domain invariants, and prints a structured report with mandatory citations — without modifying any files. This is a report-only skill. It never auto-fixes business rule violations because the semantic and patient-safety impact is too high for machine judgment.

When to Use This Skill

Activate when the user:

Says "business-compliance" followed by a URL, component name, or page name
Asks to audit domain rules, business rules, or invariants on a screen
Says "check the business logic", "audit the domain rules", "business review"
Wants to verify that a screen enforces the documented invariants from
```
docs/domain/
```

Relation to

design-compliance

design-compliance

and

business-compliance

are complementary but separate skills:

	`design-compliance`	`business-compliance`
Audits	Visual / presentation layer	Domain / business logic layer
Source of truth	`hexagone-preset.js` , CLAUDE.md, design rules	`docs/domain/` (DDD structured Markdown)
Mode	Auto-fix all violations	Report only, never fix
Risk profile	Low (cosmetic)	High (patient safety, regulatory)
Reviewer	Frontend devs	Domain experts, clinical PO, compliance

Do not merge them. Run both separately when needed. A unified

screen-compliance

aggregator is out of scope for v1.

Core Principles

1. Full Autonomy

The entire pipeline runs without asking questions during execution
If no argument is provided, ask the user what to review — then run autonomously
No files are modified. The report is printed to the terminal only

2. Report-Only — No Auto-Fix

Auto-fixing a business rule violation is categorically unsafe in healthcare software. A machine "fix" could:

Turn a warning into a block (halting legitimate care)
Turn a block into a warning (industrializing the shortcut anti-pattern)
Silently change clinical semantics without human review

The skill surfaces, documents, and cites — a human (developer + domain expert) decides the fix.

3. Schema-First

The skill requires

docs/domain/

to follow a structured rule schema (see

reference/rule-schema.md

). If the schema is not respected, the skill refuses to audit and emits a migration checklist. Garbage in → hallucinated findings out. This is non-negotiable.

4. Deterministic Matching Pipeline

Matching a rule to a screen is done in a deterministic pipeline before any LLM reasoning:

Screen extraction (deterministic) — route, Pinia stores, API endpoints, TypeScript types
Bounded context pre-filter (deterministic) — via
```
api_prefixes
```
in rule frontmatter
Entity lookup (deterministic) — match extracted types against rule
```
entities:
```
lists
Rule reasoning (LLM) — confined to the shortlisted rules

LLM is used only in step 4. Steps 1-3 are mechanical.

5. Sensitivity Over Specificity

In healthcare, false negatives are catastrophic, false positives are annoying. The skill tunes for sensitivity: when uncertain, it reports with status

NEEDS_CLINICAL_REVIEW

rather than dropping the rule silently.

6. Citation-Mandatory

Every finding MUST cite:

The exact rule file + line (or heading anchor) in
```
docs/domain/
```
The exact code file + line for the violation
The stable
```
rule_id
```
(e.g.,
```
ADM-001
```
,
```
PRESC-014
```
)

A finding without all three citations is rejected from the report. No citation = no finding.

Source of Truth (Priority Order)

Rule files in
docs/domain/
— the only source of authoritative business rules
Rule schema —
```
reference/rule-schema.md
```
(this skill's contract for rule structure)
Ubiquitous language —
```
UBIQUITOUS_LANGUAGE.md
```
if present, used to reconcile entity naming

The skill does NOT invent rules. If a rule is not documented in

docs/domain/

, it does not exist for this skill.

Input Modes

Same three input modes as

design-compliance

URL Mode

/business-compliance http://localhost:5173/hexagone-etab/vue/prescriptions/123

Use the URL to resolve the route in the router config
Find the component file for that route
Recursively resolve the component tree

Component Name Mode

/business-compliance PrescriptionEditor

Glob for matching files:

**/PrescriptionEditor.vue

**/prescription-editor.vue

Resolve the route (if any) for bounded-context inference
Recursively resolve the component tree

Page Name Mode

/business-compliance Prescriptions

Search router config for route name or path match
Find the assigned component
Recursively resolve the component tree

No Argument

/business-compliance

Ask the user what to audit. Do not assume.

Workflow

Step 1: Validate Rule Schema

Before doing anything else, validate that

docs/domain/

follows the required schema:

Locate
docs/domain/
in the project. If it does not exist, abort with:
"No
docs/domain/
directory found.
business-compliance
requires documented domain rules. See
reference/rule-schema.md
for the required format."
Parse each
.md
file in
```
docs/domain/
```
and verify the frontmatter:
- Required fields:
```
bounded_context
```
  ,
```
entities
```
  ,
```
api_prefixes
```
  (can be empty list),
```
rule_id
```
  OR a list of rules with
```
rule_id
```
  each,
```
severity
```
  ,
```
layer
```
- Acceptable values for
```
severity
```
  :
```
P1
```
  ,
```
P2
```
  ,
```
P3
```
  ,
```
P4
```
- Acceptable values for
```
layer
```
  :
```
client
```
  ,
```
server
```
  ,
```
both
```

If any file fails validation, abort the audit and emit a migration checklist:

docs/domain/ schema violations — audit aborted

| File | Missing fields | Action |
|------|----------------|--------|
| docs/domain/prescriptions.md | severity, layer | Add frontmatter fields |
| ... | ... | ... |

Fix the rule files before re-running. See skills/business-compliance/reference/rule-schema.md.

If all files validate, build the normalized in-memory rule index:
- Keyed by
```
(bounded_context, entity, rule_id)
```
- Each entry holds: rule text, severity, layer, api_prefixes, source file + line

Step 2: Resolve Target Files

Same resolution strategy as

design-compliance

Parse the user's input to determine the mode (URL, component name, page name)
Find the entry-point file(s):
- URL → parse path, search router files (
```
**/router/**/*.{js,ts}
```
  ,
```
**/router.{js,ts}
```
  ) for matching route, get component
- Component name → glob for
```
**/<name>.vue
```
  ,
```
**/<name-kebab>.vue
```
  ,
```
**/<Name>/**
```
- Page name → search router config for route name or path match
Recursively resolve the component tree:
- Read each
```
.vue
```
  file
- Extract all local imports (skip
```
primevue/*
```
  ,
```
vue
```
  ,
```
vue-router
```
  ,
```
pinia
```
  ,
```
node_modules
```
  ,
```
@hexagone/shared
```
  )
- Follow each import, repeat until no new local components
Report the discovered tree to the user

Step 3: Extract Screen Artifacts

For each file in the component tree, extract the artifacts needed for rule matching:

Route information:
- Route path (e.g.,
```
/prescriptions/:id
```
  )
- API prefix derived from the route (e.g.,
```
/api/prescriptions
```
  )
Pinia stores:
- ```
import { usePrescriptionStore } from '...'
```
- Store names are strong hints for bounded context
API endpoints:
- Grep for
```
axios.*
```
  ,
```
fetch('...')
```
  ,
```
useFetch(...)
```
  ,
```
$api.*
```
- Capture full URLs and HTTP methods
- Capture error handling:
```
catch (err)
```
  blocks, 4xx/5xx handlers
TypeScript types:
- Types imported from
```
@/types/
```
  ,
```
@hexagone/shared/types
```
  , or local
```
types.ts
```
- Focus on entity-like types:
```
Prescription
```
  ,
```
Admission
```
  ,
```
Patient
```
  ,
```
Order
```
  , etc.
Form fields and bindings:
- ```
v-model
```
  bindings
- Form validation rules (
```
required
```
  ,
```
rules
```
  ,
```
schema
```
  , Zod/Yup/Valibot schemas)
- ```
:disabled
```
  ,
```
v-if
```
  ,
```
v-show
```
  on action buttons (state machine signals)
Action handlers:
- Click handlers on buttons whose label matches a state transition (
```
save
```
  ,
```
validate
```
  ,
```
discharge
```
  ,
```
sign
```
  ,
```
cancel
```
  )
- Capture what state change they trigger via the API

Output a per-file extraction summary:

PrescriptionEditor.vue:
  route: /prescriptions/:id
  api_prefixes: [/api/prescriptions, /api/allergies]
  stores: [usePrescriptionStore, usePatientStore]
  types: [Prescription, AllergyCheck, Patient]
  actions: [save, validate, sign]

Step 4: Match Rules to Screen

For each file's extracted artifacts, match applicable rules:

Bounded context filter: for each
```
api_prefix
```
in the screen, collect rules whose
```
api_prefixes
```
frontmatter overlaps
Entity filter: intersect with rules whose
```
entities
```
list contains any extracted TS type name
Ubiquitous language reconciliation: if
```
UBIQUITOUS_LANGUAGE.md
```
exists, use it to map code-level names to domain-level names before matching (e.g.,
```
Rx
```
→
```
Prescription
```
)

Output the rule shortlist per file:

PrescriptionEditor.vue: 7 applicable rules
  - PRESC-001 (P1) — Allergy check required before validation
  - PRESC-002 (P1) — Electronic signature required on save
  - PRESC-014 (P2) — Signature requires audit log entry
  - ADM-008 (P3) — Patient must have active admission
  - ...

Step 5: Static Analysis — Detect Violations

For each (file, applicable rule) pair, check the 5 violation categories:

Category 1: Missing Precondition Check

Rule states a precondition that must hold before an action (
```
X requires Y verified
```
)
Check: does the UI guard the action (via
```
:disabled
```
,
```
v-if
```
, form validation, or API precondition)?
Evidence required: code location of the action + absence of the guard
Severity inherits from the rule

Category 2: Forbidden Transition Exposed

Rule states a state transition is forbidden (
```
Discharged cannot return to Active
```
)
Check: does the UI expose a button/action that can trigger the forbidden transition?
Evidence: button handler + API call that would cause the forbidden state change

Category 3: Required Field Absent

Rule mandates a field must be collected/displayed (e.g., "INS mandatory for clinical action")
Check: is the field present in the form template + bound via v-model + enforced by validation?
Evidence: template search + validation schema inspection

Category 4: Cross-Entity Invariant Unenforced

Rule spans entities (e.g., "Prescription must reference active AllergyCheck")
Check: does the screen load/reference both entities, and does it gate the action on the cross-entity condition?
Evidence: both stores/types present + conditional on the cross-entity relationship

Category 5: Workflow Gap

Rule defines a workflow step (e.g., "Verbal order requires countersignature within 24h")
Check: is the step surfaced in the UI, even as a reminder or follow-up action?
Evidence: presence or absence of the UI artifact mapped to the workflow step

Server-Side Rule Handling

When a rule has

layer: server

layer: both

The UI is NOT expected to fully enforce the rule
The UI IS expected to handle the server rejection gracefully (catch 409/422, show user-visible error)
Check: does the API call site include a proper error handler?
A missing error handler on a server-enforced rule is itself a violation (Category 1 — missing precondition handling)

Step 6: Handle Uncertainty

When the skill cannot confidently determine if a rule applies or is violated:

Do not drop the rule silently
Emit a finding with status
```
NEEDS_CLINICAL_REVIEW
```

Include a structured question for the reviewer:

NEEDS_CLINICAL_REVIEW — PRESC-007
Rule: Prescriptions require electronic signature.
Screen: PrescriptionEditor.vue uses usePrescriptionStore.save() but signature step not clearly detected.

Please confirm:
(a) Rule applies, step missing → fix required
(b) Rule applies, step present but undetected → add code annotation or test anchor
(c) Rule does not apply → document why in commit message or rule exclusion

Step 7: Track Non-Evaluable Rules

After analysis, list any rule that was in the shortlist but could NOT be evaluated (e.g., code too complex, dynamic dispatch, external library call). This prevents "no violations found" from being confused with "not audited":

Non-evaluable rules (5):
  - PRESC-022 — dynamic dispatch on action name, cannot trace
  - ADM-014 — relies on backend orchestration not visible in screen code
  - ...

Step 8: Generate Report

Print a structured report to the terminal:

markdown

## Business Compliance Report

**Target:** [component/page name or URL]
**Files analyzed:** [count]
**Rules indexed:** [count from docs/domain/]
**Rules applicable to target:** [count]
**Violations detected:** [count]
**Uncertain findings (NEEDS_CLINICAL_REVIEW):** [count]
**Non-evaluable rules:** [count]

### Rule Index Summary
| Bounded Context | Rules | Files |
|-----------------|-------|-------|
| prescriptions   | 14    | docs/domain/prescriptions.md |
| admissions      | 8     | docs/domain/admissions.md |
| ...             | ...   | ... |

### Files in Component Tree
| # | File | Applicable Rules | Violations |
|---|------|------------------|------------|
| 1 | `frontend/gap-mf/src/views/PrescriptionEditor.vue` | 7 | 2 |
| 2 | `frontend/gap-mf/src/components/AllergyBanner.vue` | 2 | 0 |
| ... | ... | ... | ... |

### Violations by Severity

#### P1 — Patient Safety ([count])
- **PRESC-001** — Allergy check required before validation
  - Rule source: `docs/domain/prescriptions.md:42`
  - Code location: `frontend/gap-mf/src/views/PrescriptionEditor.vue:118`
  - Category: Missing precondition check
  - Evidence: `validate()` handler calls `prescriptionStore.validate()` without prior check on `allergyCheckStore.verified`.
  - Suggested action (NOT applied): add `:disabled="!allergyChecked"` to the Validate button, or guard inside the handler.

#### P2 — Regulatory / Compliance ([count])
...

#### P3 — Clinical Workflow Integrity ([count])
...

#### P4 — Data Quality / Interoperability ([count])
...

### NEEDS_CLINICAL_REVIEW ([count])
- **PRESC-007** — [structured question as in Step 6]

### Non-Evaluable Rules ([count])
- **PRESC-022** — dynamic dispatch on action name, static trace impossible

### Drift Signals
- Rule files unchanged in > 6 months while referenced entities evolved: [list]
- Rules with no applicable screen in this audit: [list]

### Summary
- **Total violations:** [count] (P1: [n], P2: [n], P3: [n], P4: [n])
- **Waivable by developer alone:** [count] (P3 + P4)
- **Require clinical / compliance sign-off:** [count] (P1 + P2)
- **No files modified.** Review the report, discuss with domain experts, apply fixes manually.

Violation Reference

5 Violation Categories

#	Category	Typical Rule Phrasing	Evidence Required
1	Missing precondition check	"X requires Y verified"	Action handler + absence of guard
2	Forbidden transition exposed	"Cannot transition from A to B"	Action handler + forbidden state change
3	Required field absent	"Field F is mandatory"	Template + validation schema
4	Cross-entity invariant unenforced	"X must reference Y"	Both entities present + conditional
5	Workflow gap	"Step S must occur within T"	UI artifact for step S

Severity Classification

Severity	Meaning	Escalation
P1	Patient safety — direct harm pathway (allergy, dose, wrong-patient, signature bypass)	Blocks merge. Clinical PO sign-off required.
P2	Regulatory / compliance — HDS, MDR, CNIL, audit log, traceability	Blocks merge. Compliance officer sign-off required.
P3	Clinical workflow integrity — state machine, orphan entities, workflow gaps	Blocks merge. Waivable by clinical PO with written justification.
P4	Data quality / interoperability — optional fields, code systems, labels	Warns. Does not block. Dev may waive.

P1 and P2 cannot be waived by a developer alone. The skill must require a named clinical or compliance reviewer in the waiver metadata when such a waiver is requested.

Healthcare Rule Examples (Hexagone Context)

See

reference/rule-schema.md

for concrete examples. Common rule categories in Hexagone:

Safety interlocks: allergy / contraindication / dose range / drug-drug interaction
Identity: INS (Identité Nationale de Santé) verification before clinical action
Prescription integrity: electronic signature, modification audit trail, verbal order countersignature
State machines: admission/discharge flow, order/result flow, care pathway steps
Interoperability: HL7/FHIR/PAM message completeness, segment ordering (Hexaflux domain)
Regulatory: audit log on writes, break-glass justification, data retention
Billing cascades: act codes blocking discharge, GHS requiring main diagnosis

Edge Cases

docs/domain/

Does Not Exist

Abort audit. Emit:

"No
docs/domain/
directory found. This skill requires documented domain rules following the schema in
reference/rule-schema.md
. Create the directory and add rule files before running."

docs/domain/

Exists but Schema Fails

Abort audit. Emit a migration checklist of schema violations per file (see Step 1.3). Do not attempt partial audit — partial data leads to false confidence.

Rule References an Unknown Entity

If a rule's

entities:

list contains a name not found anywhere in the codebase:

Keep the rule in the index
Flag in the drift signals section of the report: "Rule X references entity Y, but no usage found in codebase"
This indicates either stale docs or a server-only entity

Screen Matches No Rules

Report "0 applicable rules" — explicitly state that this is not the same as "compliant". The screen may operate on an undocumented bounded context (which is itself a drift signal to report).

Conflicting Rules

If two rules in the index share the same

rule_id

or make contradictory claims about the same entity:

Report the conflict in the Drift Signals section
Do not attempt to resolve it — this is a domain expert decision

Dev Server Not Running

This skill does NOT require a dev server. It is a static analysis + doc-parsing skill. Visual inspection is out of scope — business rules are about code behavior, not rendering.

Large Component Tree (20+ files)

Process all files. Organize report by file for readability. Use parallel sub-agents only if the tree exceeds 10 files AND the rule index exceeds 30 rules, to keep LLM reasoning context manageable.

Mixed Micro-Frontends

Apply the same rule index to all files regardless of MF. Note MF membership per file in the report.

Waiver Requested

The skill does NOT manage waivers. If a finding must be waived, the developer does so in the PR description or a dedicated waiver log outside this skill's scope. The skill always re-reports the finding on next run — it's not the skill's job to remember waivers (memory of waivers is a human-process concern).

Important Notes

This skill does NOT modify files. It is strictly report-only. If the user says "fix them", explain that business rule violations are not mechanically fixable — the report provides suggested actions that a human must apply.
Every finding cites rule_id + doc:line + code:line. A finding without all three is a bug in the skill — do not emit it.
P1 / P2 violations require named sign-off from a clinical or compliance reviewer. The skill calls this out in the report.
Tune for sensitivity, not specificity. Better to raise 10 possible findings and let the team dismiss 9 than to miss 1 P1.
Uncertain findings →
NEEDS_CLINICAL_REVIEW
. Never silently drop a rule.
Drift signals are first-class. Rules that haven't been touched while their entities have changed → surface in the report. Rules referencing unknown entities → surface.
Non-evaluable rules are first-class. "No violations found" must not be confused with "not audited". Always list non-evaluable rules explicitly.
No auto-fix. Ever. No v2 auto-fix. If requested, push back: healthcare semantic changes require human judgment.
Pilot first. In a fresh rollout, start with ONE bounded context (suggest: prescriptions — highest stakes, clearest invariants) before expanding. Validate signal-to-noise on that pilot before adding domains.

business-compliance

NPX Install

Tags

SKILL.md Content