# acceptance-design

Adopt this skill: https://proskills.md/skills/other/okgrit-done-is-a-claim-skills-acceptance-design

Page: https://proskills.md/skills/other/okgrit-done-is-a-claim-skills-acceptance-design
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/acceptance-design/SKILL.md
size: 3172
sha: ef811311c34f1703393a3f2428db145193f05881
upstream: https://github.com/okgrit/done-is-a-claim/blob/main/skills/acceptance-design/SKILL.md

```text
---
name: acceptance-design
description: "Define executable acceptance for a bounded task before work or dispatch. Use when writing a worker brief, selecting success checks, or repairing an acceptance contract that cannot test the intended outcome."
---

# Acceptance design

Acceptance connects the user's outcome to an observable check. Design it before
implementation, and give the worker the exact contract the reviewer will use.
These are operational instructions, not measured failure-rate claims.

## Define the experiment

1. Name the outcome, affected boundary and scope. Check the command, loader,
   artifact or user flow actually affected; a helper test alone may miss the
   boundary defect. Identify what the check deliberately leaves untested.
2. Name the target host or platform, runner, dependencies, permissions and
   inputs. Confirm required source files exist in the delivered base and
   travel with the brief. Distinguish existing input paths from files to create.
3. Record the exact command, expected observable result and evidence location.
   Test that it launches on the target environment before dispatch. Prefer a
   repository script when shell quoting or setup would make the command fragile.
   Do not depend on an undocumented interpreter or hidden login state.
4. Scope every planned write, including tests and generated artifacts. Make
   predecessors available in the delivered base, or route the task to a
   checkout that contains them. A named branch is not necessarily accessible.

## Separate change from preservation

- For a defect or new behavior, demonstrate that the check rejects the old
  behavior for the intended reason when feasible. A missing tool or test path
  is not that demonstration. If a baseline run is unavailable, state the gap.
- For preservation, establish the existing behavior and require it to remain
  valid. Do not demand a failing baseline for behavior meant to stay unchanged.
- Vary meaningful inputs and inspect outputs where the contract depends on
  them. A mocked success, repeated implementation constant or file's existence
  may prove less than the required outcome. Include relevant regression scope.
- If a worker cannot run a required live-service or platform check, assign it
  to a suitable verifier and retain it as required. Local success cannot stand
  in for the missing boundary check.

## Freeze and correct the contract

Put the exact commands, inputs, preservation requirements and stop conditions
in the brief. Worker and reviewer use the same contract on identified trees.
If the check is wrong or unrunnable, report the mismatch before continuing
dependent work. The task owner records the old and replacement contracts, the
reason and how the replacement still tests the intended outcome. Revalidate
the replacement before resuming; do not silently lower a threshold, remove a
failing case or relabel a failure as success. A changed user requirement is a
scope change to record, not evidence that the old contract passed.

Acceptance is designed when it can distinguish the required outcome from a
plausible failure, runs where assigned, and preserves the agreed boundaries.
```

## File: README.md
upstream: https://github.com/okgrit/done-is-a-claim/blob/main/README.md

````text
# Done is a claim

**English** · [Türkçe](README.tr.md)

<picture>
  <source media="(prefers-reduced-motion: reduce)" srcset="assets/receipt.svg">
  <img src="assets/receipt-stamp.gif" alt="Done is a claim. A red SHOW THE RECEIPT stamp lands on the ivory cover.">
</picture>

[Replay stamp](assets/receipt-stamp.gif) · [Static cover](assets/receipt.svg)

**Your agent says “done”. What would prove it?**

An evidence-first development workflow for coding agents: **understand → plan →
implement → diagnose → review → verify → deliver**. 15 connected skills, 18
incident-backed rules, and optional tools that keep the evidence attached to the
work it tested. Small tasks take a shorter path.

[Get started](#get-started) · [Use in your project](docs/REPORTS.md) · [Follow the workflow](docs/WORKFLOW.md) · [Choose a skill](#choose-a-skill) · [Try the demo](#watch-a-false-green)

## Get started

**Recommended first use: one small task in a project you already have.**

**1. Install with your coding agent.** Give it this request:

> Install https://github.com/Grit-77/done-is-a-claim. Follow INSTALL.md, preserve
> my existing instructions and settings, verify the installation, and explain
> what changed and how I start using it. Use my current account and permissions.

**For the installing agent:** follow [INSTALL.md](INSTALL.md). Identify the
current host and installation scope, preserve existing work, verify the result,
and finish with a short explanation in the user's language.

**2. Open a fresh session in your project and choose a small task.** Include
your actual bug or change request, then add:

> Use using-done-is-a-claim for this task. Before editing, identify the observable
> result and the check that can test it. Take a proportionate path through the
> work and review. Report the actual result, tested inputs and remaining gaps.
> Continue within my existing authorization.

**3. Inspect the result, then tell us what happened.** Can you identify the
check that ran, what it established, and anything still unverified? If the
skill did not load or the check could not run, keep that visible. For an optional
saved command receipt, follow [the existing-project guide](docs/REPORTS.md).

[Share a first-use report](https://github.com/Grit-77/done-is-a-claim/issues/new?template=use-report.yml):
include your client, release or revision, task, observed result and uncertainty.
A failure or confusing step is useful feedback too. Remove private information
before sharing. Installing instructions does not enforce agent compliance.

### Manual installation

Install all skills as a native plugin:

**Claude Code**

```bash
claude plugin marketplace add Grit-77/done-is-a-claim --scope local
claude plugin install done-is-a-claim@done-is-a-claim-marketplace --scope local
```

**Codex**

```bash
codex plugin marketplace add Grit-77/done-is-a-claim
codex plugin add done-is-a-claim@done-is-a-claim-marketplace
```

Start a fresh session. In Claude Code, invoke
`/done-is-a-claim:using-done-is-a-claim`; in Codex, select
`using-done-is-a-claim` through `/skills` or the `$` skill picker.
[Plugin scope, updates and validation limits →](docs/PLUGINS.md)

Prefer project-local copies or the rules alone? Use a [toolkit clone](#watch-a-false-green):

| You use | Add to your project |
|---|---|
| Codex or an agent that reads `AGENTS.md` | Copy [AGENTS.md](AGENTS.md) to the project root. |
| Claude Code | Copy [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md), which imports it with `@AGENTS.md`. |
| Existing instructions | Merge the relevant rules into your file. Keep your project-specific commands and constraints. |

You can start with that one rules file. Native plugin installation does not add
these rules to the adopting project's instructions.
[Installation options on macOS, Linux or Windows →](docs/INSTALL.md)

Want the workflow in your project without overwriting existing files? From this clone,
replace `../my-project` with your existing project path and preview the copy:

```bash
python tools/install_skills.py --project ../my-project --agent codex --profile workflow --dry-run
```

Then omit `--dry-run` to install. For Claude Code, use `--agent claude-code`.
Existing skill destinations are refused; your project instructions stay untouched.
Use `--list` to see profiles and individual skills. Explicit `--update` can replace
unmodified installer-owned copies while retaining backups; local edits are refused.

## Watch a false green

Try the local example with **Python 3.10+**:

```bash
git clone https://github.com/Grit-77/done-is-a-claim.git
cd done-is-a-claim
python examples/false_green.py
```

**Synthetic demo:** the verifier fails with exit **1**; the summarizer displays
its output and exits **0**. The receipt follows the verifier and says **FAIL**.
The demo itself exits **0** because it exposed the mismatch—not because the
verifier passed.

<picture>
  <source media="(prefers-reduced-motion: reduce)" srcset="assets/demo/false-green-recorded.png">
  <img src="assets/demo/false-green-recorded.gif" alt="Recorded synthetic output: verifier exit 1, summarizer exit 0, receipt FAIL. Demo exit 0 means the mismatch was demonstrated.">
</picture>

[Runnable source](examples/false_green.py) · [Static proof](assets/demo/false-green-recorded.png) · [Recording and limits](docs/demo-recording.md)

Recorded output excerpts, paced for reading. This is a synthetic demonstration,
not a production log or an agent-performance benchmark.

## One workflow, short paths

**Use it during ordinary development:** [shape a feature, implement with tests,
resolve PR feedback, and keep the task across interruptions →](docs/DAILY-WORK.md)

Start with [using-done-is-a-claim](skills/using-done-is-a-claim/SKILL.md). It routes
substantial work through planning and execution, sends unexpected results into
diagnosis, and closes review findings with fixes and fresh checks. A clear, small
change goes straight from inspection to implementation, review and verification.
Workers are optional; an unavailable reviewer is reported as a self-review limit.

[See the flow and a worked task →](docs/WORKFLOW.md)

Want to test your installation on real work? From this repository's clone, create a small broken CSV project,
let your installed skill handle it, then check the result independently:

```bash
python tools/native_smoke.py create --project ../claim-smoke
python tools/native_smoke.py verify --project ../claim-smoke --json
```

The initial independent check deliberately fails even though the starter's narrow
tests pass. The tool creates and checks the fixture; you run the agent through
your normal host and account. [Real session procedure and observed limits →](docs/NATIVE-TESTS.md)

## Check the delivered artifact

A successful copy can also deliver the wrong artifact. The
[delivery demo](examples/wrong_delivery.py) contrasts a stale copy, the correct
copy, and identical bytes that still fail to parse:

```bash
python examples/wrong_delivery.py
```

It uses temporary local fixtures. Exit zero means the traps were demonstrated,
not that a real delivery succeeded.

## Get a real receipt

[Three field notes and a real PR: what did the check actually prove? →](docs/FIELD-NOTES.md)

**Already have a project and a test command?** [Capture your check and bring a
Markdown or JSON evidence summary to your next PR →](docs/REPORTS.md). The report
separates the command's historical result from current evidence freshness.
Arguments, raw logs and filenames are omitted by default; it does not publish
anything or declare your task complete.
For CI consumers, `--format json` emits a minimal v1 projection with the same
reporter exit status. The guide lists its exact fields and disclosure limits.

Capture a command's own exit, full output and Git state with the optional local tool:

```bash
python tools/receipt.py -- python tools/run_tests.py
```

It writes a fresh `receipt.json` and `command.log` under `.local/receipts/`.
Use `--input` to fingerprint
````