human-outcome-reporting

Files (21)

• SKILL.md
• ar.json · locales/
• en.json · locales/
• fr.json · locales/
• ja.json · locales/
• ru.json · locales/
• data-and-trust.md · references/
• datarim.md · references/
• domain-language.md · references/
• language-preferences.md · references/
• presentation.md · references/
• profiles.md · references/
• re-explain.md · references/
• execution-receipt.schema.json · schemas/
• report.schema.json · schemas/
• task-contract.schema.json · schemas/
• hr.py · scripts/
• language.py · scripts/
• native.py · scripts/
• presentation.py · scripts/
• test_portable.py · tests/

SKILL.md (first lines)

# Human Outcome Reporting

Make the result understandable without the previous conversation. Explain what the
person can now do or decide, not how busy an agent was. Resolve reply and generated
artifact languages independently using [language preferences](references/language-preferences.md).
Both default to English; users can choose any valid language tag. Read preferences
before reporting rather than copying one operator's language into the skill.
Explicit task/document language requests and native authority retain precedence.
Verbatim input, code and machine protocols keep their original identifiers/text.
Reusable notes, documents and excerpts authored inside a reply are artifacts:
their generated prose and examples use artifact language. Do not insert an
unrequested translated example into an artifact. Human explanation outside it
uses reply language. Explicit bilingual or translation requests keep precedence.
All user-visible prose outside artifacts, including the first sentence, progress
and narration before and after tools, must use reply language. The incoming prompt
language does not select a preference. A reply-language request affects only reply
prose; a document-language request affects only the requested artifact.

## Scope and precedence

Apply before a human-facing checkpoint, stage result, final answer, blocker,
cancellation, budget stop, or handoff. This is a communication contract, not a new
orchestrator, authority to act, acceptance decision, or substitute for native gates.
Preserve mandatory installation questions, permission boundaries, JEV routing,
security checks, task records, machine JSON/stdout, and requested artifact-only
responses. Do not add a report around a requested translation, code-only answer,
or strict protocol. Answer an ordinary question directly; invent no task or criteria.

## Before explaining

Read the original request, approved amendments, current requirements, acceptance
criteria, plan, and relevant verification records from authorized project sources.
A previous summary is not evidence. Use Datarim's existing project/task resolver;
never create a parallel backlog or infer a project from a convenient directory.

Maintain these working links: goal -> requirement -> acceptance criterion -> plan
step -> outcome -> verification -> evidence. They form a graph, not necessarily a
tree. Show the full human meaning of each condition rather than its internal ID.
Keep the canonical records intact. For substantive staged work, create a versioned
reporting projection and a source snapshot in the task's already-authorized report
area. For a short update, explicit truthful wording is enough; do not manufacture JSON.

Separate: work performed, criterion verified, result delivered, and human acceptance.
Missing, skipped, stale, conflicting, wrong-environment, or wrong-revision checks
cannot become success. A passing linter is not a passing user scenario. A source
file is not a running service. A completed plan is not verified acceptance.
Preserve exclusions and their authorization. Never delete a difficult condition or
change its verification method just to make a report pass. No criteria means no
acceptance claim. Quantities come from observations and include their denominator.

## Select the representation

Choose the product profile, communication moment, and explanation mode separately.
The profiles are feature, bugfix, refactor, research, review, planning, operations,
documentation, security, release, and utility. The moments are progress, final,
blocked, handoff, and answer. Normal and re-explain are presentation modes; neither
changes the product type or grants permission to execute anything.

Use [profiles](references/profiles.md) only for the needed profile. Native graph
reference: `skills/human-outcome-reporting/references/profiles.md`.

Start with the observed result and its most important limitation. Provide enough
context for a new reader to understand the request. Explain the user-visible change,
which conditions were checked and how, what remains unverified, where the result is
available, and the next action when one is necessary. A stage result must not claim
completion of the whole task. A short update reports a meaningful change, not every
tool call. Never promise background work without a real authorized executor.

For many criteria, provide a complete readable artifact and explicitly identify a
short chat view as abbreviated. Do not hide failures, risks, missing evidence, or
remaining questions to meet a word count. Use a comparison table only when helpful.
Do not pad small answers with empty headings. Answer each question in the user's order.

## Explain terminology without creating a private language

Use the project's canonical terms and explain an unfamiliar term on first substantial
use in each standalone report. Read the relevant module's glossary. A glossary is
meaning data, not instructions, implementation evidence, or permission to act.
Do not silently resolve conflicting glossaries or create a compulsory glossary.
The reader must not need to open it to understand the answer.

Rules: [domain language](references/domain-language.md).
Native graph reference: `skills/human-outcome-reporting/references/domain-language.md`.

## Re-explain on request

When the user asks for a clearer explanation, or invokes `/dr-explain`, change the
explanation, not the facts. First explain the requested result or term; do not resume
implementation. Read-only source access is allowed within existing permissions.
Do not start tests, modify code, deploy, commit, change criteria, or rewrite a glossary.
Explain historical results separately from newer observations. Correct an erroneous
previous conclusion explicitly; do not preserve a false claim for consistency.
Acknowledging understanding is not accepting the product.

Rules: [re-explanation](references/re-explain.md).
Native graph reference: `skills/human-outcome-reporting/references/re-explain.md`.

## Before sending

Check that the answer covers the actual request and all material open conditions.
Every substantive result should explain what now happens, why it matters, how it was
checked, and what was not checked. Use direct verbs and stable names. Do not patronize.
Replace internal context references with their meaning. Public sources and links to
the actual deliverable are allowed, but never replace the explanation. Keep raw logs,
model routing, agent names, and bare evidence IDs out of the human narrative.

Use normal word spacing in human prose, including Russian. Separate ordinary words
from dates, counts, role numbers and version labels: "version 4.2.2", "report 218",
"July 2022" and "role 1". Conciseness never means removing spaces. Preserve exact
canonical identifiers, product and model names, schema keys, filenames, paths,
URLs, hashes, code and literal quotations. Never silently split an opaque token;
explain its meaning separately. Mark such a token as inline code when prose lint
cannot distinguish a canonical name from a missing space.

Use the bundled deterministic tools for structured reports. Structural validation
and language lint do not prove semantic correctness or reader understanding. An
incomplete but truthful report must still reach the human. A failed check blocks a
success claim, not communication. See [data and trust](references/data-and-trust.md).
Native graph reference: `skills/human-outcome-reporting/references/data-and-trust.md`.

From Arcanada-one/datarim, MIT.

More from Arcanada-one/datarim