pharaoh-review-completeness

Name: pharaoh-review-completeness
Availability: InStock
Author: useblocks

Audit needs.json for missing reviewer and approved_by fields against artefact-catalog.yaml.

24|Updated Feb 12, 2026

Search Tags:#audit #review #approval #findings #needs #pharaoh #artefact-catalog

Ready to run

npx skills add https://github.com/useblocks/pharaoh --skill pharaoh-review-completeness

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: pharaoh-review-completeness
Source: https://github.com/useblocks/pharaoh/tree/main/skills/pharaoh-review-completeness
Command: npx skills add https://github.com/useblocks/pharaoh --skill pharaoh-review-completeness

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Use when inspecting one or more needs for review / approval-chain completeness. Flags needs missing required :reviewer: or :approved_by: fields per the project's artefact catalog. Emits one finding per incomplete need via pharaoh-finding-record.

Core Features & Use Cases

Atomicity
(a) Indivisible — one lookup + one field-presence check per need.
(b) Input: {project_dir, need_ids?: list[str]} (if need_ids omitted, iterate all). Output: [{need_id, missing_roles: [str]}] (empty list if all complete).
(c) Reward: deterministic — field-present vs field-absent. 100% target on fixture.
(d) Reusable: audit orchestrators, standalone CI gate, pre-merge check.
(e) Composable: read-only over needs.json + artefact-catalog.yaml.
Process
Step 1: Load artefact catalog
For each artefact type, extract required_roles — which may include reviewer, approved_by, or be absent (no review required).
Step 2: Load needs
Read <project_dir>/needs.json (or the pre-built bazel artefact). For each need matching need_ids (or all needs if none given), determine its artefact type from its ID prefix.
Step 3: Check required roles
For each need whose type has required_roles, verify each required role field is present in the need's options and non-empty. Collect missing roles.
Step 4: Emit findings
For each need with at least one missing role, emit a finding record:

{
  "need_id": "<id>",
  "missing_roles": ["reviewer", "approved_by"]
}

Output is a JSON list of such objects, wrapped in a single fenced json block. Empty list → [].
Input / output example
Input call (as audit subagent):

pharaoh-review-completeness on project <Score dir> for all component-level reqs

Output:

[
  {"need_id": "gd_req__timestamp_recording", "missing_roles": ["approved_by"]}
]

Failure modes
artefact-catalog.yaml absent → emit [] with stderr warning; skill is a no-op without tailoring.
needs.json absent → emit [] with stderr warning.
Malformed artefact catalog → emit [] with stderr warning "artefact-catalog malformed".
Composition
Consumed by pharaoh-audit-fanout as sub-area 4. Each returned finding is passed to pharaoh-finding-record with category: missing_reviewer or category: missing_approval.

Frequently Asked Questions about pharaoh-review-completeness

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I audit project needs for missing reviewer and approved_by fields?▼

Auditing needs for missing reviewer and approved_by fields is done by reading the artefact-catalog.yaml for required roles and scanning needs.json to report missing fields per need. The output is a deterministic JSON list of findings with need_id and missing_roles.

What happens if the artefact-catalog.yaml or needs.json file is absent when checking requirements?▼

If the artefact-catalog.yaml or needs.json file is absent, the audit emits an empty list with a stderr warning. The skill acts as a no-op without the artefact catalog present, ensuring CI gates do not fail on missing configuration.

Can I check review and approval completeness for specific need IDs instead of all project requirements?▼

Yes, you can check review and approval completeness for specific need IDs by providing a list of need_ids in the input. If need_ids are omitted, the skill iterates over all needs in the needs.json file to verify required roles.

How does the review completeness audit handle needs that do not require approval?▼

When an artefact type in the artefact-catalog.yaml has absent required_roles, meaning no review is required, the audit skips field-presence checks for those needs. It only collects missing roles for needs whose type explicitly requires reviewer or approved_by fields.

What is the best way to integrate missing approval findings into a continuous integration pipeline?▼

The best way to integrate missing approval findings into a CI pipeline is using the skill's JSON output wrapped in a fenced block. Each finding record is passed to pharaoh-finding-record with categories like missing_reviewer or missing_approval for downstream tracking.

Why does the needs audit output an empty list for a malformed artefact catalog?▼

The needs audit outputs an empty list with a stderr warning stating 'artefact-catalog malformed' to prevent pipeline failures on configuration errors. This deterministic behavior ensures downstream pharaoh-finding-record integration receives valid, parseable JSON.