---
name: carbon-human
description: Ask, retain, and record the smallest set of project-specific human decisions that materially change CARBON confidence, readiness, risk, test selection, or release interpretation. Use when intent, risk appetite, workflow fit, domain judgment, consequence, taste, accountability, or a missing test oracle needs human input.
---

# CARBON Human Decision Context

Before any inspection or tool call, read and follow [the CARBON command start preview](../../runtime/carbon/references/command-start-preview.md). Show the tailored high-level approach in chat before beginning the workflow.

CARBON is the first AI Agentic Verification Harness. It can inspect code and
evidence, but it must not silently invent human intent, taste, consequence,
domain judgment, accountability, or a release decision. This workflow is an
optional near-final evidence layer: it qualifies confidence and directs future
work without blocking a technical confidence assessment.

Read [the human decision context contract](../../runtime/carbon/references/human-decision-context.md) before generating questions or interpreting answers.

## Start the durable human context

1. Follow workspace onboarding and start the required live command-progress
   checklist immediately after the preview.
2. Call `carbon_human_context` with `action=status` before generating anything.
3. Call `carbon_human_context` with `action=generate`, the active project root,
   and `size=quick` unless the user explicitly asks for a deeper pass. Preserve
   the user’s named feature, release, or decision as `scope`.
4. Use the local project, recent CARBON runs, findings, plans, test results, and
   missing evidence to review the returned questions. Ask only the highest-value
   open questions in chat—normally no more than five. Do not turn this into a
   generic requirements questionnaire.
5. Update the live checklist after inspection, question selection, and any
   answer persistence. The `carbon_human_context` result opens the protected
   **CARBON Human workspace** beside chat by default. It is the primary answer
   surface: select a quick option, add nuance, or leave a project-level note.
   Every save records project-local context and refreshes the durable branded
   report snapshot. Also generate the required command report and open it
   beside chat.

The durable file is `<project>/.carbon/human/decision-context.json`. It is
project-local, permissions-restricted, and is not a place for credentials or
private secrets.

## What makes a good question

Prioritize a question only when the answer could materially change a test
oracle, test priority, safety boundary, confidence interpretation, readiness,
or release decision. Typical high-value gaps include:

- Did we solve the customer’s actual problem, or only the literal prompt?
- Is this a demo, internal trial, staged rollout, or production decision?
- What happens when it fails, who absorbs the damage, and what is unacceptable
  even once?
- What domain invariant or exceptional workflow would an expert know but the
  code and tests cannot reveal?
- Does the experience feel credible and acceptable in the real customer
  workflow? What confusion, surprise, or loss of trust is unacceptable?
- Who owns detection, recovery, communication, rollback, and making users
  whole?
- What are the coding agent and automated evaluators not asking?

Do not ask for facts already observable in the project. Do not ask trivial,
ceremonial, or broad questions that do not change a decision. Keep observed
technical evidence separate from an answer or a person’s preference.

## Record answers

When the user provides an answer, persist it immediately using:

`carbon_human_context action=answer root=<project> questionId=HUM-... answer=<exact answer> answeredBy=<optional role>`

If several answers arrive, record each answer against its own question ID.
Never invent an answer, infer approval from silence, or substitute an agent’s
opinion for a human answer. If the user requests refresh after material context
changes, call `action=generate refresh=true`; preserve previous answers and
unanswered questions.

When options are returned for a question, prefer the interactive Human
workspace so a person can record a common decision in one click and optionally
add context. A written answer remains valid where no option fits. The workspace
also supports a comment on every question and a project-level decision note;
all are durable local context for the agent’s next CARBON pass.

## Use in confidence work

Every broad `/carbon` pass should run a quick `action=generate` near the final
confidence step after observed evidence, persona exploration, and risk ranking.
It may continue and publish confidence if no person answers. In that case state
plainly that confidence covers observed technical evidence only and is
qualified by unrecorded intent, risk appetite, experience judgment,
consequence, domain expertise, and accountability. Open human questions are
not failed tests and do not lower an observed result by themselves.

When answers exist, use them to guide the current and future plan, confidence,
readiness, risk, persona charters, test selection, and release interpretation.
They never convert unobserved behavior into a pass and never remove human
release authority.

## Required HTML result

Before the final chat response, follow [command result reporting](../../runtime/carbon/references/command-result-reporting.md). Generate the branded single-file command page, pass `specialistIds=["jason"]`, open it inside the coding agent, and end with the current host’s **Open the CARBON report** link. The report must show open versus answered questions, why each open question matters, the confidence qualifier, the durable local path, quick-answer options, recorded comments, and exact answer syntax. Present the Human workspace link first so it opens in the side view whenever the host supports it; the static report remains the durable, shareable local snapshot.
