hipaa-assessor

name	hipaa-assessor
description	Assess a target system against HIPAA Privacy Rule, Security Rule, and Breach Notification Rule using the hipaa-foundation repository, including entity-role triage, addressable-spec handling, domain selection, evidence mapping, and structured draft output.
origin	hipaa-foundation

HIPAA Assessor

Use this skill to produce conservative draft HIPAA assessments of software systems.

This skill is the workflow layer only. It is not the knowledge base itself. The canonical corpus stays in the hipaa-foundation repository under core/.

For fast navigation inside this skill package, start with START-HERE.md and references/index.yaml. They point back to canonical files under the resolved foundation repo. They do not replace them.

Source hierarchy

• FOUNDATION_ROOT/core/regulations/*.yaml authoritative_text — binding regulatory text
• FOUNDATION_ROOT/core/guidance/*.yaml — OCR guidance and interpretive context
• FOUNDATION_ROOT/core/domains/*.yaml and checklist files — non-authoritative assessment guidance
• target-system evidence — determines the actual finding

When to use

Use this skill when:

• the user asks to assess, review, or evaluate a system against HIPAA
• the hipaa-foundation repository is available directly or through a separate checkout

Prerequisites

Before starting, you need:

• a target system to assess
• enough repo-local evidence to begin answering the triage questions
• a resolvable hipaa-foundation repository

If the target system or foundation root cannot be identified, stop and ask for the missing path. Otherwise inspect the target repo first and ask follow-up questions only if the assessment is still blocked.

Locate the foundation repo

Resolve the foundation root before reading any core/ files.

Resolution order (implemented in scripts/resolve-foundation-root.sh):

1. HIPAA_FOUNDATION_ROOT environment variable (fail closed if set but invalid)
2. Cross-tool config file: ${XDG_CONFIG_HOME:-$HOME/.config}/hipaa-assessor/config (single line, absolute path)
3. Well-known path: $HOME/github/hipaa-foundation
4. Current working directory if it is the foundation repo
5. Sibling of the target repo root (walk up to .git, check sibling)
6. Sibling of cwd (fallback if not inside a git repo)

Run scripts/resolve-foundation-root.sh from this skill package. Once resolved, treat that absolute path as FOUNDATION_ROOT and read all referenced files from there.

Workflow

Before triage, explore the target repo directly. Use code, docs, infrastructure config, tests, and any in-repo architecture or procedural material as assessment evidence.

Ask follow-up questions only when a required decision cannot be derived from the reviewed corpus and the assessment would otherwise be blocked.

Step 0 -- Check content policy

Read:

• FOUNDATION_ROOT/core/provenance/content-policy.yaml
• FOUNDATION_ROOT/core/provenance/decision-log.yaml

Do not use the repo in a way that violates the content policy.

Step 1 -- Entity-role triage

Read:

• FOUNDATION_ROOT/core/applicability/triage.yaml
• FOUNDATION_ROOT/core/applicability/triage-output-template.yaml

Entity type must be determined from evidence in the reviewed corpus: governance documents, BAAs, formal scope statements, or explicit entity classification records. Do not infer entity type from system function, clinical branding, device names, or health-data content. If the corpus does not confirm entity type, use tbd with low confidence.

When entity_type is tbd and ePHI is clearly in scope, the usual applicable_rules posture is security_rule, breach_notification_rule, and enforcement_rule. Do not add privacy_rule unless entity status is confirmed from the corpus. Always include enforcement_rule for context.

Before selecting domains, produce a structured triage block.

At minimum include:

• entity_type (covered_entity, business_associate, ba_subcontractor, not_regulated, tbd)
• covered_entity_type (provider, health_plan, clearinghouse, not_applicable, tbd)
• hybrid_entity_status (yes, no, tbd)
• entity_type_confidence (low, medium, high)
• phi_types_in_scope
• phi_scope_confidence (low, medium, high)
• evidence_basis (repo-only, repo-plus-external-evidence, repo-plus-runtime-or-interviews)
• assessment_confidence (low, medium, high)
• applicable_rules
• part_162_assessment_mode (not_in_scope_v1, applicability_only, full_module)
• state_law_overlay_status (out_of_scope_v1, identified, tbd)
• in_scope_domains
• excluded_domains
• open_decisions

After producing the triage block:

• Apply domain_selection_rules from triage.yaml to populate in_scope_domains.
• Read only the domain files listed in in_scope_domains. Skip excluded domains entirely.
• Retain entity-and-applicability in working context throughout the assessment. It governs downstream scope judgments.
• If entity_type is tbd, read FOUNDATION_ROOT/docs/example-assessment-entity-tbd.md for patterns on handling unconfirmed entity type, excluded Privacy domains, and evidence-basis limitations.
• If entity_type is business_associate or ba_subcontractor, read FOUNDATION_ROOT/docs/example-assessment-ba.md for BA-specific assessment patterns.
• If entity_type is covered_entity, read FOUNDATION_ROOT/docs/example-assessment.md for covered-entity assessment patterns.

If entity_type is not_regulated, state why and stop.

Step 2 -- Select domains

Read:

• FOUNDATION_ROOT/core/index/domain-inventory.yaml

Select domains from the canonical inventory based on entity type, applicable rules, and PHI scope.

Step 3 -- Explore evidence

Read:

• FOUNDATION_ROOT/core/checklists/evidence-map.yaml

Use the evidence map while exploring:

• code
• infrastructure
• docs
• external governance evidence

Evidence basis branching:

• If evidence_basis is repo-only, read the repo_only_notes in each in-scope domain file's assessment_guidance before scanning. These notes identify which controls are typically organizational and should not be rated Gap on repo-only evidence alone.
• If evidence_basis includes external evidence, also consult the external evidence expectations in each domain's regulation files.

Step 4 -- Assess each domain

Read:

• FOUNDATION_ROOT/core/checklists/assessment-rubric.yaml

For each in-scope domain:

1. Read the domain file (review_questions, deep_assessment_probes, assessment_guidance).
2. Read the domain's regulation_files/standards for orientation.
3. Read the domain's regulation_files/implementation_specifications for detail on each standard's required and addressable specs.

Read all listed regulation files for the current domain before moving to the next domain. Do not front-load regulation files for all domains at once. Work domain by domain.

For every in-scope domain:

• compare expected evidence to reviewed evidence
• separate missing evidence from observed gaps
• for Security Rule addressable specs, capture the disposition: implemented, alternative, documented_exception, or not_evidenced
• a documented exception backed by a risk analysis is Adequate, not a gap
• keep conclusions proportional to the evidence basis

Addressable-spec handling:

• required + implemented -> Adequate
• required + not implemented -> Gap
• addressable + implemented -> Adequate
• addressable + alternative (documented) -> Adequate
• addressable + documented_exception (documented risk basis) -> Adequate
• addressable + not_evidenced -> Partial or Not assessed depending on evidence basis

Repo-only realism rule: Many HIPAA obligations are organizational. On repo-only evidence, the following should typically be Not assessed or Partial, not Gap:

• notices of privacy practices
• authorizations
• accounting of disclosures
• sanctions policy execution evidence
• executed BAAs
• training completion records
• breach investigation and notification workflow execution evidence

Domain severity anchors:

• For systems with strong technical controls but weak governance, default to Minor or Observation
• Escalate only with explicit rationale
• State the escalation rationale if overriding the domain default

Step 5 -- Produce the assessment

Use:

• FOUNDATION_ROOT/docs/assessment-output-template.md

Every output must:

• begin with the exact disclaimer as the very first content: This is a draft assessment for human compliance review. It is not a compliance determination and not a substitute for legal counsel.
• end with the same exact disclaimer as the very last content
• include the triage block before findings
• include a domain ratings summary table with an addressable_disposition column for Security Rule specs
• include a detailed finding section for every row that is not Adequate or Not applicable
• show basis_type for each non-trivial finding

If part11-foundation is also being used:

• keep the same factual evidence across both assessments
• let part11-foundation own Part 11 record/signature scope and control ratings
• let hipaa-foundation own HIPAA Privacy/Security/Breach findings
• do not force identical labels when the repos are answering different questions

If gamp5-foundation is also being used:

• let gamp5-foundation own lifecycle, validation, and supplier methodology
• HIPAA risk analysis and GAMP risk assessment are related but distinct

Step 6 -- Self-review

Run:

• FOUNDATION_ROOT/core/checklists/assessment-self-review.md

If any check fails, go back and correct the assessment.

Output rules

• never present repo interpretation as binding regulatory text
• never hide uncertainty in prose
• never treat addressable specs as gaps without documenting disposition
• never collapse missing evidence and actual control gaps into one vague finding
• never produce findings for Part 162 in v1
• always keep the assessment usable as a draft review artifact for human compliance reviewers

When information is insufficient

If the available information is not enough to answer a triage question or assess a domain:

• do not guess
• use Not assessed or Partial, whichever the rubric supports
• state what information is needed
• continue on assessable domains