business-compliance

What this skill does

# 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:
1. **Screen extraction** (deterministic) — route, Pinia stores, API endpoints, TypeScript types
2. **Bounded context pre-filter** (deterministic) — via `api_prefixes` in rule frontmatter
3. **Entity lookup** (deterministic) — match extracted types against rule `entities:` lists
4. **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)

1. **Rule files in `docs/domain/`** — the only source of authoritative business rules
2. **Rule schema** — `reference/rule-schema.md` (this skill's contract for rule structure)
3. **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
```
1. Use the URL to resolve the route in the router config
2. Find the component file for that route
3. Recursively resolve the component tree

### Component Name Mode
```
/business-compliance PrescriptionEditor
```
1. Glob for matching files: `**/PrescriptionEditor.vue`, `**/prescription-editor.vue`
2. Resolve the route (if any) for bounded-context inference
3. Recursively resolve the component tree

### Page Name Mode
```
/business-compliance Prescriptions
```
1. Search router config for route name or path match
2. Find the assigned component
3. 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:

1. **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."

2. **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`

3. **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.
   ```

4. **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`:

1. **Parse the user's input** to determine the mode (URL, component name, page name)
2. **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
3. **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
4. **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:

1. **Route information**:
   - Route path (e.g., `/prescriptions/:id`)
   - API prefix derived from the route (e.g., `/api/prescriptions`)

2. **Pinia stores**:
   - `import { usePrescriptionStore } from '...'`
   - Store names are strong hints for bounded context

3. **API endpoints**:
   - Grep for `axios.*`, `fetch('...')`, `useFetch(...)`, `$api.*`
   - Capture full URLs and HTTP methods
   - Capture error handling: `catch (err)` blocks, 4xx/5xx handlers

4. **TypeScript types**:
   - Types imported from `@/types/`, `@hexagone/shared/types`, or local `types.ts`
   - Focus on entity-like types: `Prescription`, `Admission`, `Patient`, `Order`, etc.

5. **Form fields and bindings**:
   - `v-model` bindings
   - Form val