---
name: deeper-signals-audit
description: >
  Use this skill whenever a user wants a constructive, evidence-based review of whether a
  psychometric or pre-hire assessment, or a battery, is documented against recognized
  testing standards. Triggers include: "review this assessment", "evidence review", "is
  this assessment well evidenced", "evaluate this test against APA/SIOP/EFPA/ITC", "what
  evidence exists for this test", "review the reliability and validity of [test]",
  "technical manual review", "DIF / adverse impact / norms / criterion validity review",
  "compare the evidence for these tools", or any request to map an assessment's evidence
  base against professional standards for selection or development use. Also triggers when a
  user uploads a technical manual, names a Deeper Signals assessment, or wants a branded
  evidence-review document. Always use it for a standards-based evidence review of an
  assessment, even if the user does not say "review". It reviews the instrument and its
  evidence, never a candidate, and produces no verdict, rating, or ranking.
license: Proprietary
---

# Assessment Evidence Review

This skill produces a constructive, neutral, evidence-based review of an assessment (or a
battery) against four professional standards (APA, SIOP, EFPA, ITC), and delivers it as a
Deeper Signals branded Word document. It reports what the evidence shows, states plainly
where information was not found in the materials reviewed, and helps the reader complete the
picture and strengthen their assessment strategy.

The booklet generator and all brand assets are vendored at `booklet/`, and the Deeper
Signals evidence file is vendored at `references/deeper_signals_factsheet.md`, so the skill
is fully self-contained and can be published online and run outside Deeper Signals.

The review evaluates an instrument and its evidence. It never produces a verdict, rating,
ranking, or endorsement, never states that a tool is or is not suitable for a use, and
never evaluates, scores, or ranks a candidate.

---

## Operating principles (non-negotiable)

1. Constructive and neutral. The report completes the picture and supports the reader's own
   evaluation. It contains no verdict, no pass or fail, and no statement of suitability.
2. Never fabricate evidence. Report only what is in the materials supplied or surfaced by a
   permitted search. If a value is not there, the status is "Not found in materials
   reviewed". Never estimate or infer a statistic, sample size, study, or citation.
3. Absence is neutral. "Not found in materials reviewed" means it was not located in what
   was reviewed. It is not a deficiency and not evidence of absence in the tool. Keep
   "Partially documented" and "Not found in materials reviewed" strictly distinct.
4. Publisher-agnostic and non-disparaging. Apply the same framework and bar to every tool.
   Report evidence, never judgments about companies.
5. Deeper Signals source of truth. Evaluate Deeper Signals tools only from
   `references/deeper_signals_factsheet.md`, and never use that file to make claims about
   another vendor's tool.
6. Cite search-derived claims, preferring peer-reviewed literature, the publisher's own
   technical documentation, and recognized reviews over blogs or marketing.
7. Use-case frames emphasis, not gating. The intended use and decision weight decide which
   standards to foreground, never a verdict.
8. Instrument, not candidate. Never produce candidate-level content, scores, or hire / no
   hire guidance.

See `references/evidence_handling.md` for the full evidence rules and the status taxonomy,
`references/standards_rubric.md` for the pillars, core areas, and context modules, and
`references/document_structure.md` for the section order and the verbatim disclaimer.

---

## Workflow

### Step 1: Run the intake

Confirm the following before producing the review, asking only for what is missing. If the
user cannot supply something, proceed and record the gap neutrally in the report.

1. Assessment name(s) and publisher(s).
2. Single instrument or battery. If a battery, how the instruments are sequenced and
   combined (for example, screen first, interview last).
3. Intended use case and sub-use: selection (hiring, promotion, succession) or development
   (coaching, team effectiveness, leadership development).
4. Decision weight: a hard screen, a decisive input, or one of several non-decisive inputs.
   Used only to frame which standards are most relevant, never to produce a verdict.
5. Population: geography, level, and any language requirements.
6. Evidence sources available:
   - For Deeper Signals assessments: the vendored Deeper Signals evidence file
     (`references/deeper_signals_factsheet.md`).
   - For any other assessment: a technical manual (uploaded), permission to search public
     sources, or both.
7. Any specific questions or concerns the user wants the review to address.

If evidence is incomplete after intake and the user permits it, search for publicly
available evidence and cite what you use. If no usable evidence is available for an
instrument at all, say so neutrally rather than producing thin or speculative findings.

### Step 2: Gather and read the evidence

- Deeper Signals tools: read `references/deeper_signals_factsheet.md`. It is authoritative
  for Core Drivers, Core Values, the Core Reasoning Suite, and the competency and
  job-profile layer. Do not use it for any other vendor.
- Other tools: read the uploaded manual with the `pdf` / `pdf-reading` skills or host PDF
  tools. If permitted, use `web_search` and cite specifics. Do not search if the user did
  not permit it.

### Step 3: Apply the standards framework

Work through the pillars and core areas in `references/standards_rubric.md` (Theoretical
rationale, Reliability, Validity, Fairness, Norms and scoring), assessing every core area.
Switch on a context module only when the use case or instrument type calls for it. Assign
each assessed area exactly one neutral status (Well documented, Documented, Partially
documented, Not found in materials reviewed, Not applicable) and write a one-line basis,
adding short neutral, sourced narrative only where an area needs more than one line.

### Step 4: Write the structured review JSON

Assemble the findings into `review.json` (schema in the builder docstring and
`references/document_structure.md`). Group findings under pillars. Include the scope, a
neutral overview, the pillar findings, the battery review (battery only), the
well-documented summary, the neutral "strengthen the picture" reframe, considerations for
the use, questions grouped by instrument, immediate and short-term next steps, scope and
confidence (with the differential-evidence note), and sources marked by kind. See
`evals/fixtures/sample_review.json` for a complete worked example using a Deeper Signals
instrument.

### Step 5: Build the booklet content

```bash
python3 scripts/build_audit_content.py /tmp/review.json /tmp/meta.json /tmp/content.json
```

`meta.json` fields are optional: `title` (default "Assessment Evidence Review"; keep it
short, it renders at 56pt), `subheading` (defaults to the assessment/battery name and
publisher), `date`. The builder enforces the section order, the neutral status-to-color
mapping, the suppressed cover tagline, and the verbatim disclaimer, and it omits thin
sections. It never invents findings, and it rejects any status outside the neutral set.

### Step 6: Generate the Word document

The booklet generator is vendored at `booklet/`. `booklet/scripts/generate_booklet.js` is a
single self-contained bundle (the MIT-licensed `docx` library is compiled in, so there is
no `node_modules` to install). It applies heading keep-with-next, widow and orphan control,
and non-splitting short table rows.

```bash
node booklet/scripts/generate_booklet.js \
  /tmp/content.json /mnt/user-data/outputs/assessment_evidence_review.docx booklet/assets

python3 booklet/scripts/embed_fonts.py \
  /mnt/user-data/outputs/assessment_evidence_review.docx booklet/assets/fonts
```

To rebuild the bundle after editing `generate_booklet.src.js`:
`npx esbuild booklet/scripts/generate_booklet.src.js --bundle --platform=node
--outfile=booklet/scripts/generate_booklet.js`.

### Step 7: QA and deliver

Render to PDF and scan every page before delivering.

```bash
python3 /mnt/skills/public/docx/scripts/office/validate.py /mnt/user-data/outputs/assessment_evidence_review.docx
python3 /mnt/skills/public/docx/scripts/office/soffice.py --headless --convert-to pdf /mnt/user-data/outputs/assessment_evidence_review.docx --outdir /tmp
pdftoppm -jpeg -r 100 /tmp/assessment_evidence_review.pdf /tmp/preview
```

Scan for, and fix and re-render until clean: a heading whose section text starts on the next
page; oversized white space; an orphaned single line; a short table row split across a page;
and any leftover verdict or pass-or-fail or suitability language. Confirm the cover has no
verdict tagline, every assessed area appears with a neutral status, "Not found in materials
reviewed" reads as neutral (never a deficiency), "Sources reviewed" lists only what was
relied on (marked by kind), and the verbatim disclaimer is the final block. Then call
`present_files` on the .docx.

---

## Guardrails (what the skill must never do)

- Never produce a verdict, rating, ranking, endorsement, or any statement that an assessment
  is or is not suitable, fit, or unfit for a use.
- Never disparage a publisher or competitor. Report evidence, not judgments about companies.
- Never fabricate, estimate, or infer a statistic, sample size, study, or citation.
- Never present "Not found in materials reviewed" as a deficiency. Keep it neutral.
- Never use the Deeper Signals evidence file to make claims about another vendor.
- Never evaluate, score, or rank a candidate, and never give hire or no-hire guidance.
- Never give legal advice.
- Never omit or alter the disclaimer.

---

## Reference files

- `references/standards_rubric.md`: the four source standards, the pillars and core areas,
  the context modules, and use-case / population sensitivity framed as emphasis.
- `references/evidence_handling.md`: the anti-fabrication rule, neutral absence, the
  differential-evidence note, the neutral status taxonomy, sourcing, and the
  publisher-agnostic / non-disparaging requirement.
- `references/document_structure.md`: the section order, concision and page-setting rules,
  and the verbatim disclaimer.
- `references/deeper_signals_factsheet.md`: the vendored Deeper Signals evidence file, the
  source of truth for Deeper Signals instruments.
- `scripts/build_audit_content.py`: turns the structured `review.json` into booklet
  `content.json`, enforcing the section order, neutral status colors, suppressed tagline,
  and verbatim disclaimer. Holds `STANDARD_DISCLAIMER`.
- `booklet/`: the vendored Deeper Signals booklet generator.
  `scripts/generate_booklet.js` is the self-contained bundle; `scripts/generate_booklet.src.js`
  is the readable source it is built from (it adds `table` and `overview_callout` block
  types and the pagination controls on top of the base booklet); `scripts/embed_fonts.py`
  embeds the brand fonts; `assets/` holds the fonts, logo, and cover gradient.
- `evals/`: scenarios and the worked `sample_review.json` fixture.

This skill is self-contained: the booklet generator, the brand assets, and the Deeper
Signals evidence file are all vendored, so it produces a branded evidence review without any
external dependency. Host requirements are Python 3 and Node.js. The QA step uses host tools
for validation and PDF rendering.
