perspective-validation

name	perspective-validation
description	Create a Perspective Validation Checklist (PVC) report for a change, workflow, schema, or policy. Use when performing socio-technical review, governance review, operational readiness review, or when a PR touches schemas/hooks/skills/tools and needs a PVC report.
argument-hint	[target] [risk_tier] [domain]
disable-model-invocation	false
user-invocable	true
allowed-tools	Read, Grep, Write, Edit, Bash, Git
context	fork
agent	general-purpose

Intent

Produce a PVC report (Perspective Validation Checklist) that scores the target against key non-type failure modes (human factors, governance, economics, adversarial security, loop stability, data governance, and legitimacy) with concrete evidence references and remediation actions.

Success criteria:

• A valid PVC report is written to docs/reviews/pvc/ and passes python skills/perspective-validation/scripts/validate_pvc.py
• Each non-N/A score is justified with at least one evidence reference
• Any FAIL/PARTIAL includes a concrete remediation action (P0/P1/P2)

References:

• CHECKLIST.md
• pvc_report_template.yaml

Inputs

Parameter	Required	Type	Description
target	Yes	string	What to review (file/dir path, workflow name, or PR/change description)
risk_tier	No	enum	low | medium | high (defaults to medium if unclear)
domain	No	string	Domain context (e.g., general, manufacturing, healthcare)
deployment	No	string	Deployment context (e.g., local-dev, customer-facing, safety-critical)

Procedure

1. Scope the review: Confirm target, domain, deployment, and risk_tier

   • If the target is a PR or branch diff, identify changed files and whether they touch critical paths (schemas/, hooks/, skills/, grounded_agency/, tools/, spec/)

2. Collect evidence: Read the minimum set of files needed to justify scores

   • Prefer evidence anchors as file:path#Lline (or file:path:line if needed)
   • When reviewing a change set, include at least one evidence item for “what changed” and “what it affects”

3. Score the checklist: For each PVC test ID (HF-101 … ECO-901), assign one of:

   • PASS: explicitly satisfied with evidence
   • PARTIAL: acknowledged but missing enforcement/measurement/runbook detail
   • FAIL: absent
   • N/A: not applicable to this target (include a brief reason in assumptions or in an action note)

4. Write the report: Create a new file in docs/reviews/pvc/ named:

   • YYYY-MM-DD_<short-slug>.pvc.yaml
   • Start from pvc_report_template.yaml, then fill it in completely

5. Validate: Run python skills/perspective-validation/scripts/validate_pvc.py

   • If it fails, fix the report until it passes

6. Summarize actions: Provide the top remediation actions (P0 first), with crisp “what to change” and “where it lives” guidance

Output Contract

Return a structured object:

pvc_report_path: string  # Path under docs/reviews/pvc/
target: string
context:
  domain: string
  deployment: string
  risk_tier: low | medium | high
scorecard:
  HF-101: PASS | PARTIAL | FAIL | N/A
  HF-102: PASS | PARTIAL | FAIL | N/A
  HF-103: PASS | PARTIAL | FAIL | N/A
  ORG-201: PASS | PARTIAL | FAIL | N/A
  GOV-202: PASS | PARTIAL | FAIL | N/A
  ECON-301: PASS | PARTIAL | FAIL | N/A
  ECON-302: PASS | PARTIAL | FAIL | N/A
  SEC-401: PASS | PARTIAL | FAIL | N/A
  SEC-402: PASS | PARTIAL | FAIL | N/A
  CTRL-501: PASS | PARTIAL | FAIL | N/A
  ASSUR-601: PASS | PARTIAL | FAIL | N/A
  ASSUR-602: PASS | PARTIAL | FAIL | N/A
  DG-701: PASS | PARTIAL | FAIL | N/A
  ETH-801: PASS | PARTIAL | FAIL | N/A
  ECO-901: PASS | PARTIAL | FAIL | N/A
actions:
  - id: string
    priority: P0 | P1 | P2
    fix: string
    artifact: doc | workflow | policy | hook | test | benchmark | code
    owner: string
confidence: number  # 0.0-1.0
evidence_anchors: array[string]
assumptions: array[string]

Example

Example: Review a workflow DSL change

Input:

target: "schemas/workflow_catalog.yaml (new gates + recovery semantics)"
risk_tier: medium
domain: general
deployment: customer-facing

Output:

pvc_report_path: "docs/reviews/pvc/2026-01-29_workflow-catalog-gates.pvc.yaml"
target: "schemas/workflow_catalog.yaml (new gates + recovery semantics)"
context:
  domain: "general"
  deployment: "customer-facing"
  risk_tier: "medium"
scorecard:
  HF-101: PARTIAL
  HF-102: FAIL
  HF-103: PARTIAL
  ORG-201: FAIL
  GOV-202: FAIL
  ECON-301: FAIL
  ECON-302: N/A
  SEC-401: PARTIAL
  SEC-402: PARTIAL
  CTRL-501: PASS
  ASSUR-601: PARTIAL
  ASSUR-602: FAIL
  DG-701: FAIL
  ETH-801: N/A
  ECO-901: PASS
actions:
  - id: "DOC-001"
    priority: P0
    fix: "Add an operator-facing incident view schema and a minimal tabletop exercise for this workflow family."
    artifact: doc
    owner: "maintainers"
confidence: 0.7
evidence_anchors:
  - "file:schemas/workflow_catalog.yaml#L1"
assumptions:
  - "No runtime UI exists; report assumes log-based incident response."

Safety Constraints

• This skill is intended to be read-mostly.
• Only write under docs/reviews/pvc/ unless the user explicitly asks for additional changes.
• Do not include secrets/PII in evidence excerpts; prefer references/hashes over raw content.