# Policy Experience > Policy Experience - Skill: `devarispbrown/policy-experience` (Agent Skill, multi-file: 12 files) - Install (CLI): `npx skillmds@latest add devarispbrown/policy-experience` - Raw SKILL.md: https://api.skillmd.com/api/skills/devarispbrown/policy-experience/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: devarispbrown (https://skillmd.com/u/devarispbrown) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/devarispbrown/policy-experience --- # Policy Experience ## Mission Turn security and compliance into self-service. Policy lives in the repository as code, guardrails enforce it automatically at the right checkpoint, developers request exceptions through an approval chain instead of filing tickets, and every approval leaves an audit trail that survives a compliance review. The failure mode this skill exists to eliminate is ticket-ops: developers discovering policy at release time, human-run checklists, approval queues, and violations that say only "policy check failed". Policy experience is developer experience: the rule is the guardrail, the message is the fix, and the exception is a request, not a ticket. Read `references/standards.md` for the canonical thresholds, severity vocabulary, and release gates. Policy work is distributed by domain. For auth and RBAC user experience use the `access-and-permissions-dx` skill; for dependency and artifact risk use the `security-supply-chain` skill; for whole-product experience measurement use the `developer-experience-auditor` skill. This skill owns the policy-as-code machinery: rules, guardrails, exceptions, approvals, and violation quality. ## Policy as self-service Run the seven steps in order. Every step ends in a verifiable artifact; step 7 assembles the report. ### 1. Inventory the policy surface Map every policy that applies to this repository: compliance frameworks, security standards, organizational policy, and product risk appetite. For each policy record: - the source requirement it derives from - the rule that encodes it - the enforcement point that will check it - the severity band (P0-P4 from `references/standards.md`) A requirement with no rule is unmet compliance exposure. A rule with no requirement is unowned automation. Both are findings. Do not re-inventory domains owned by sibling skills: dependency and artifact rules belong to `security-supply-chain`; permission-model rules belong to `access-and-permissions-dx`. Duplicate rule inventory is how policies drift. ### 2. Encode policies as code Read `references/policy-as-code.md`. Rules are data in the repository, versioned with the code, reviewed in PRs, and machine-checkable. Policy files are the single source of truth. Tickets, dashboards, and compliance reports derive from them; nothing is written back to a ticket system. Verify: - every rule has a stable policy id and names its source requirement - policy changes go through the same review flow as code changes - the guardrail test suite proves the rule fires on violations and stays silent when compliant ### 3. Wire guardrails into the flow Read `references/guardrail-design.md`. Attach each rule to the earliest checkpoint where a violation is actionable: pre-commit, PR check, CI, merge queue, deploy pipeline, or runtime enforcement. Verify: - P0/P1 rules block; P2 warns with a deadline; P3/P4 advise - pre-deploy guardrails default to blocking, runtime guardrails to log-and-alert - every guardrail run records a result and evidence; no silent failures - a guardrail that cannot run reports UNVERIFIED, never PASS ### 4. Write actionable violations Read `references/violation-actionability.md`. Every violation stands alone: what happened, why, how to fix, and the request-exception route. Validate violation samples with `scripts/check_policy_actionability.py`; an opaque sample set exits 1. An opaque violation is a defect in the policy system, not a developer failure. Severity P1, and it triggers the `UNEXPLAINED_ERROR` release gate. ### 5. Design self-service exceptions Read `references/exception-flows.md`. Exceptions are requested in the repository — a PR, a form, a command — never filed in a ticket queue. The request names the policy, the scope, the duration, and the rationale; the approval chain scales with severity; the exception expires and the guardrail re-blocks. Verify: - no self-approval, at any severity - every request records an outcome: approved, denied, expired, revoked - a denial returns remediation guidance, not silence ### 6. Make approvals auditable Read `references/approval-auditability.md`. Every approval and denial appends to an immutable trail: actor, action, policy id, timestamp, evidence, justification. The trail is the compliance evidence. Verify: - the trail is append-only and tamper-evident - guardrail runs are recorded alongside approvals - active exceptions reconcile with approved requests; expired exceptions are gone ### 7. Verify and report Re-run the guardrail suite, re-check violation samples, and render the audit report from `assets/policy-audit-template.md`. Return exactly one verdict: PASS / PASS WITH DEBT / FAIL / UNVERIFIED. A gate failure forces FAIL; a score never overrides a gate; missing evidence is UNVERIFIED, never PASS by assumption. ## Guardrail contract Every guardrail records its id, the policy id it enforces, its checkpoint, and its blocking flag. Every run records a result — PASS, FAIL, or UNVERIFIED — with evidence. No silent failures. Guardrail configuration changes go through the same PR flow as code; disabling a guardrail is a policy change that is reviewed, recorded, and reversible. ## Violation message contract A machine-readable violation carries the four actionability fields, keyed as used by `scripts/check_policy_actionability.py`: - `what_happened` — the policy id and the concrete observation: rule, target, and value - `why` — the rule and its rationale - `how_to_fix` — the exact remediation, preferably copy-paste commands - `request_exception` — the self-service route when the rule cannot be satisfied Every violation must also identify its policy id and where the problem lives (file:line or resource). A violation missing any field is opaque: severity P1, and it triggers `UNEXPLAINED_ERROR` at release gates. The developer never needs to open the policy file to act. ## Exception request contract A self-service exception request contains: 1. policy id and rule being deviated from 2. scope: resources, paths, environments 3. duration and expiry 4. rationale and risk assessment 5. remediation plan for the deviation 6. requester and the approval chain for its severity Approval chains scale with severity; no self-approval at any level. The chain and the outcome are recorded in the audit trail. Exceptions expire; renewal is a new request with fresh rationale. ## Audit trail contract Every entry records timestamp, actor, action, policy id, scope, evidence hash, and justification. Entries are append-only and tamper-evident; retention follows compliance requirements; the trail is exportable in JSON or CSV. The trail must answer who approved what, why, when, for how long, and on what evidence. ## Required output For every policy engagement, produce the policy audit report using `assets/policy-audit-template.md`. The report must contain: 1. **Verdict** — exactly one of PASS / PASS WITH DEBT / FAIL / UNVERIFIED 2. **Evidence** — repository/revision, environment, checks executed and not executed, with evidence labels 3. **Policy inventory** — policy id, source requirement, rule location, severity, guardrail checkpoint 4. **Guardrail results** — per-guardrail result with evidence; no unrecorded runs 5. **Violation actionability** — per-violation field coverage; opaque violations listed as findings 6. **Exceptions** — request, scope, duration, approver chain, status, expiry, evidence 7. **Audit trail summary** — recent entries and reconciliation of active exceptions 8. **Gate results** — per-gate result keyed by gate constant, with evidence 9. **Backlog** — prioritized P0-P4 debt ## Definition of done Policy experience work is done when: - every requirement maps to a rule and every rule maps to a requirement - policy files live in the repository and are reviewed like code - guardrails enforce at the earliest actionable checkpoint with recorded evidence - every violation passes the actionability check; none is opaque - exceptions are self-service, approved by the right chain, and expire - the audit trail proves who approved what, why, and until when - the report is rendered from `assets/policy-audit-template.md` with one verdict - no gate failure is hidden by a score, a missing run, or an assumption