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.mdpvc_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
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/)
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”
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)
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
Validate: Run python skills/perspective-validation/scripts/validate_pvc.py
- If it fails, fix the report until it passes
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.
1---2name: perspective-validation3description: 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.4---5
6## Intent
7
8Produce 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.
9
10**Success criteria:**
11- A valid PVC report is written to `docs/reviews/pvc/` and passes `python skills/perspective-validation/scripts/validate_pvc.py`
12- Each non-N/A score is justified with at least one evidence reference
13- Any FAIL/PARTIAL includes a concrete remediation action (P0/P1/P2)
14
15**References:**
16- `CHECKLIST.md`
17- `pvc_report_template.yaml`
18
19## Inputs
20
21| Parameter | Required | Type | Description |
22|-----------|----------|------|-------------|
23| `target` | Yes | string | What to review (file/dir path, workflow name, or PR/change description) |
24| `risk_tier` | No | enum | `low \| medium \| high` (defaults to `medium` if unclear) |
25| `domain` | No | string | Domain context (e.g., `general`, `manufacturing`, `healthcare`) |
26| `deployment` | No | string | Deployment context (e.g., `local-dev`, `customer-facing`, `safety-critical`) |
27
28## Procedure
29
301) **Scope the review**: Confirm `target`, `domain`, `deployment`, and `risk_tier`
31 - 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/`)
32
332) **Collect evidence**: Read the minimum set of files needed to justify scores
34 - Prefer evidence anchors as `file:path#Lline` (or `file:path:line` if needed)
35 - When reviewing a change set, include at least one evidence item for “what changed” and “what it affects”
36
373) **Score the checklist**: For each PVC test ID (HF-101 … ECO-901), assign one of:
38 - PASS: explicitly satisfied with evidence
39 - PARTIAL: acknowledged but missing enforcement/measurement/runbook detail
40 - FAIL: absent
41 - N/A: not applicable to this target (include a brief reason in `assumptions` or in an action note)
42
434) **Write the report**: Create a new file in `docs/reviews/pvc/` named:
44 - `YYYY-MM-DD_<short-slug>.pvc.yaml`
45 - Start from `pvc_report_template.yaml`, then fill it in completely
46
475) **Validate**: Run `python skills/perspective-validation/scripts/validate_pvc.py`
48 - If it fails, fix the report until it passes
49
506) **Summarize actions**: Provide the top remediation actions (P0 first), with crisp “what to change” and “where it lives” guidance
51
52## Output Contract
53
54Return a structured object:
55
56```yaml
57pvc_report_path: string # Path under docs/reviews/pvc/
58target: string
59context:
60 domain: string
61 deployment: string
62 risk_tier: low | medium | high
63scorecard:
64 HF-101: PASS | PARTIAL | FAIL | N/A
65 HF-102: PASS | PARTIAL | FAIL | N/A
66 HF-103: PASS | PARTIAL | FAIL | N/A
67 ORG-201: PASS | PARTIAL | FAIL | N/A
68 GOV-202: PASS | PARTIAL | FAIL | N/A
69 ECON-301: PASS | PARTIAL | FAIL | N/A
70 ECON-302: PASS | PARTIAL | FAIL | N/A
71 SEC-401: PASS | PARTIAL | FAIL | N/A
72 SEC-402: PASS | PARTIAL | FAIL | N/A
73 CTRL-501: PASS | PARTIAL | FAIL | N/A
74 ASSUR-601: PASS | PARTIAL | FAIL | N/A
75 ASSUR-602: PASS | PARTIAL | FAIL | N/A
76 DG-701: PASS | PARTIAL | FAIL | N/A
77 ETH-801: PASS | PARTIAL | FAIL | N/A
78 ECO-901: PASS | PARTIAL | FAIL | N/A
79actions:
80 - id: string
81 priority: P0 | P1 | P2
82 fix: string
83 artifact: doc | workflow | policy | hook | test | benchmark | code
84 owner: string
85confidence: number # 0.0-1.0
86evidence_anchors: array[string]
87assumptions: array[string]
88```
89
90## Example
91
92### Example: Review a workflow DSL change
93
94**Input:**
95```yaml
96target: "schemas/workflow_catalog.yaml (new gates + recovery semantics)"
97risk_tier: medium
98domain: general
99deployment: customer-facing
100```
101
102**Output:**
103```yaml
104pvc_report_path: "docs/reviews/pvc/2026-01-29_workflow-catalog-gates.pvc.yaml"
105target: "schemas/workflow_catalog.yaml (new gates + recovery semantics)"
106context:
107 domain: "general"
108 deployment: "customer-facing"
109 risk_tier: "medium"
110scorecard:
111 HF-101: PARTIAL
112 HF-102: FAIL
113 HF-103: PARTIAL
114 ORG-201: FAIL
115 GOV-202: FAIL
116 ECON-301: FAIL
117 ECON-302: N/A
118 SEC-401: PARTIAL
119 SEC-402: PARTIAL
120 CTRL-501: PASS
121 ASSUR-601: PARTIAL
122 ASSUR-602: FAIL
123 DG-701: FAIL
124 ETH-801: N/A
125 ECO-901: PASS
126actions:
127 - id: "DOC-001"
128 priority: P0
129 fix: "Add an operator-facing incident view schema and a minimal tabletop exercise for this workflow family."
130 artifact: doc
131 owner: "maintainers"
132confidence: 0.7
133evidence_anchors:
134 - "file:schemas/workflow_catalog.yaml#L1"
135assumptions:
136 - "No runtime UI exists; report assumes log-based incident response."
137```
138
139## Safety Constraints
140
141- This skill is intended to be **read-mostly**.
142- Only write under `docs/reviews/pvc/` unless the user explicitly asks for additional changes.
143- Do not include secrets/PII in evidence excerpts; prefer references/hashes over raw content.
144
majiayu000