policy-lifecycle-analyst - SKILL.md Agent Skill

name: policy-lifecycle-analyst description: > Policy and procedure lifecycle management specialist for CyberRadar. Covers full policy lifecycle: template library (500+ mapped to SCF/frameworks), rich text policy editor with version control, policy-to-control-to-framework mapping, policy gap analysis, approval workflows (integrates with existing approval chains), distribution and acknowledgment tracking, policy refresh scheduling, AI-assisted policy generation hooks, and policy compliance scoring that feeds into Cyber Score. Triggers on: policy, procedure, policy template, policy gap, policy approval, policy version, policy distribution, policy acknowledgment, policy generation, policy compliance.

Act as Policy Lifecycle Management Lead for CyberRadar.

Mission

Build a complete policy management module that replaces manual Word/PDF policy creation with a governed, trackable, framework-aligned policy lifecycle — from AI-assisted drafting through approval, distribution, acknowledgment, and refresh.

Policy Lifecycle Stages

1. DRAFT → AI-assisted or template-based creation
2. REVIEW → Stakeholder review with inline comments
3. APPROVAL → Approval chain workflow (existing Sprint 3 feature)
4. PUBLISHED → Active policy, distributed to stakeholders
5. ACKNOWLEDGED → Stakeholders confirm receipt and understanding
6. ACTIVE → Policy in effect, monitoring compliance
7. REVIEW_DUE → Refresh cycle triggered, back to REVIEW
8. RETIRED → Superseded or no longer applicable

Data Model

policies — policy records (RLS)
  id uuid PK, tenant_id uuid, title text NOT NULL,
  policy_number text UNIQUE per tenant, category text NOT NULL
  ('security','privacy','compliance','operational','hr','it','risk','business_continuity'),
  content_html text NOT NULL, content_plain text NOT NULL,
  summary text, effective_date date, review_date date,
  owner_id uuid FK→users, department text,
  status text NOT NULL DEFAULT 'draft',
  version int NOT NULL DEFAULT 1, parent_id uuid FK→policies (previous version),
  framework_ids uuid[] DEFAULT '{}', control_ids uuid[] DEFAULT '{}',
  scf_control_ids text[] DEFAULT '{}',
  ai_generated boolean DEFAULT false, ai_model_version text,
  created_at timestamptz, updated_at timestamptz

policy_templates — template library (platform-level + tenant custom)
  id uuid PK, tenant_id uuid NULL (null = platform template),
  title text NOT NULL, category text NOT NULL,
  content_template text NOT NULL, variables jsonb DEFAULT '{}',
  framework_ids uuid[], scf_control_ids text[],
  industry text, region text, language text DEFAULT 'en',
  usage_count int DEFAULT 0

policy_acknowledgments — who acknowledged what (RLS)
  id uuid PK, tenant_id uuid, policy_id FK→policies,
  user_id uuid FK→users, acknowledged_at timestamptz,
  method text ('email_link','in_app','sso_prompt'),
  ip_address text, user_agent text

policy_distributions — distribution tracking (RLS)
  id uuid PK, tenant_id uuid, policy_id FK→policies,
  distribution_type ('all_users','role_based','department','custom'),
  target_roles text[], target_departments text[], target_user_ids uuid[],
  distributed_at timestamptz, total_recipients int,
  acknowledged_count int DEFAULT 0, pending_count int

policy_gap_analysis — gap detection results (RLS)
  id uuid PK, tenant_id uuid, framework_id uuid,
  total_required int, covered_by_policy int, gap_count int,
  gaps jsonb, recommendations jsonb, analyzed_at timestamptz

Template Library (500+)

Map every template to SCF controls using scf_control_ids
SCF mapping ensures templates auto-align to ANY framework the tenant activates
Categories: Information Security (120+), Privacy (80+), Compliance (100+), Operational (60+), HR Security (40+), IT Operations (50+), Risk Management (30+), Business Continuity (20+)
Each template has variables: {{organization_name}}, {{effective_date}}, {{owner}}, {{review_period}}, {{regulatory_reference}}
Regional variants: Saudi (SAMA/NCA/PDPL-specific), US, EU, UK, APAC

Policy Gap Analysis

For each active framework: check which requirements/controls have mapped policies
Identify: missing policies, outdated policies (past review_date), draft-only (not published)
Score: policy_coverage_pct = covered / total_required × 100
This feeds into Cyber Score "Policy Coverage" dimension

AI Integration Hooks (connects to Sprint 7 AI layer)

POST /v1/ai/policy/draft → generates policy from template + framework + tenant context
POST /v1/ai/policy/analyze → checks existing policy for gaps, conflicts, clarity
POST /v1/ai/policy/update → suggests updates based on regulatory changes
AI features disabled by default; use mock provider in dev

Approval Integration

Uses existing approval_chains from Sprint 3
Policy approval creates approval_request with entity_type='policy'
On approval → status transitions to 'published'
On rejection → status back to 'draft' with reviewer comments

Downstream Wiring

policy.published → evidence-svc auto-generates evidence for mapped controls
policy.acknowledged → compliance score update
policy.review_due → notification + task creation
policy.gap_detected → Cyber Score policy dimension degrades
Policy coverage feeds into board report

Anti-Patterns

NEVER allow policy publication without at least one approval
NEVER skip version control — every edit creates a new version
NEVER delete policies — only retire (audit trail)
NEVER distribute without tracking acknowledgment
NEVER auto-approve AI-generated policies — human review required