# runx Skill Quality Standard

Every first-party runx skill should produce a human-useful artifact for a
declared audience, grounded in evidence, specific enough to review or act on,
and honest enough to stop when the evidence is weak.

This standard is prompt contract, not only evaluator policy. Skill instructions
should make the agent generate better work before any downstream gate runs.

At runtime, runx parses each skill's `## Quality Profile`, injects it into
agent-mediated work as `quality_profile`, and pins the profile hash in the
receipt under `metadata.quality_profiles`. Receipts carry the hash, not the
full profile body, so later review can prove which quality contract governed
the run without bloating or leaking prompt text into receipts.

## Required Profile

Each serious skill should make these parts explicit in its own terms:

- `purpose`: the job the skill exists to perform.
- `audience`: who reads, reviews, publishes, or acts on the artifact.
- `artifact_contract`: the concrete output and required fields.
- `evidence_bar`: what must be grounded, cited, or named as missing.
- `voice_bar`: how the artifact should read. See VOICE.md for the canonical
  voice grammar; runx injects it into every agent context as
  `voice_profile` and pins its hash in the receipt under
  `metadata.voice_profile`.
- `strategic_bar`: why the artifact matters for the graph's purpose.
- `stop_conditions`: when the skill should return `needs_more_evidence`,
  `needs_review`, `needs_agent`, or a comparable stop state instead of
  polishing weak work.

## Universal Quality Bar

- Lead with the human problem, decision, or next action.
- Name concrete pain, tradeoffs, and boundaries; avoid generic automation
  claims.
- Turn evidence into claims, examples, constraints, and decisions. Do not dump
  raw issue threads, receipts, amendments, or builder packets into reader-facing
  prose.
- Match the target project's vocabulary and ambition. Do not default to AI,
  launch, preview, migration, adoption, scaffold, or demo framing unless the
  source surface itself uses those terms.
- Never describe surfaced work as machine output, agent output, model output, or
  AI-generated content. The artifact should read like a maintainer-owned piece
  of work.
- If the evidence is thin, say so and stop narrowly. Do not fill the gap with
  plausible prose.

## Evidence Bar

- Separate verified evidence from inference.
- Cite the source surface, file, receipt, or external reference that supports a
  claim.
- Preserve provenance without turning provenance into the public artifact.
- Name missing evidence as a blocker when it would change the recommendation.

## Strategic Bar

Strategic quality is graph-specific. A skill proposal, Sourcey docs pass,
ecosystem brief, issue reply, and outreach packet should not share one action
taxonomy. They should share one discipline:

- the graph purpose decides the action
- prior art and research provide context
- the artifact must make a concrete human decision easier
- weak opportunity, weak evidence, or weak fit should stop the graph cleanly

## Forbidden Reader-Facing Framing

Avoid these phrases in surfaced artifacts unless quoted from source evidence:

- "generated by AI", "AI-generated", "machine-generated"
- "machine output", "agent output", "model output"
- "the machine should", "the agent should", "the model should"
- "supplied catalog", "supplied decomposition", "supplied work-plan"
- "provided catalog evidence"
- "builder envelope", "machine packet" outside a provenance note

Use concrete nouns instead: current catalog, source thread, available evidence,
receipt, issue, draft PR, generated site, decision packet, docs page, advisory,
or named skill.

## Stop Conditions

Stopping is a high-quality outcome when the graph lacks enough evidence or
strategic fit. Prefer a precise stop state over polished filler:

- `needs_more_evidence`: the artifact would require claims not supported by the
  source surfaces.
- `needs_agent`: required inputs, policy, or trust boundaries are missing.
- `needs_review`: the artifact exists but does not meet the declared quality
  profile.
- `not_worth_publishing`: the work is true but not useful enough for the
  declared audience or graph purpose.
- `voice_mismatch`: the artifact would require generic AI framing, filler
  structure, or register drop to satisfy the declared voice contract. See
  VOICE.md for the voice grammar that every reader-facing artifact must meet.
