# Brief artifacts

Use this reference only for the `BRIEF` mode of `nobrainer-writing`. Pick one
artifact and keep the output small enough that a busy reader can decide or act
without reconstructing the story.

## The common shape

```text
Title: <observable failure or user outcome>
Problem or goal: <one sentence>
Impact or value: <who is affected and why it matters>
Evidence or context: <reproduction, example, link, version, or UNKNOWN>
Acceptance or question: <how we know what to do or what answer is needed>
Next action: <one owner/action, if relevant>
```

Use only fields that change triage or implementation. Do not add a history
section, root-cause theory, solution design or generic closing unless the reader
needs it to act. Facts from the requester outrank polished wording; unknowns
stay visible.

Task-shaped artifacts (`BUG`, `ISSUE`, `USER_STORY`, `REQUEST` and `TASK`) always
expose two fields:

- `Description`: what is wrong, needed or intended.
- `Definition of Done (DoD)`: the observable closure condition and required proof.

Keep `Acceptance` for observable product behavior; do not hide the description or
DoD inside `Problem`, `Context`, `Done when` or a generic paragraph. `COMMENT`
is intentionally smaller and does not need task fields.

Number every acceptance criterion sequentially as `AC01`, `AC02`, `AC03` and so
on. Start at `AC01`, do not leave gaps, and do not use anonymous bullets or
checkboxes under `Acceptance`. DoD remains separate and may reference the AC IDs.

Before compressing, keep a private ledger of material facts: when it started,
what did or did not happen, exact statuses/errors, conditions, uncertainty and
the requested action. A concern is not proof of a failure, and a request to know
whether something is safe is not permission to invent the policy that decides
it. If the source does not define the desired behavior, write the open decision
or `UNKNOWN` instead of adding a warning, retry rule, UI state or implementation.

## COMMENT

Use for code review, issue updates, decisions, questions and status. Start with
the observation or decision, then the impact, evidence and one request.

```text
ENV: <Name> | URL: <route or N/A> | User: <role or redacted alias>
<Observation or decision>. <Why it matters or what changed>.
<Requested action or question>.
Evidence: <file, line, test, link or concrete example>.
```

Good code-review comment:

> ENV: TEST | URL: N/A | User: reviewer
>
> This returns `200` when the provider times out, so the caller treats a failed
> sync as success. Return the error or mark the result `UNKNOWN`, and add a
> timeout test; evidence: `sync_provider()` line 84 and the missing-timeout test.

Good status comment:

```text
ENV: QA | URL: https://demo.example.test/runs/42 | User: qa-operator
The timeout is now reported as a failed sync, and test `provider_timeout_marks_failure` passes. Next: review the PR.
```

Do not turn a comment into a mini-report. If there is no concrete observation,
write a direct question instead of praise followed by a vague suggestion.

## BUG

Title the observable failure, not a guessed cause.

````text
Title: [Bug] <what fails> when <condition>

Description: <one sentence describing the failure>

ENV:
- Name: <QA | DEV | TEST | PROD | PREPROD | BETA | UNKNOWN>
- URL: <exact non-secret route or page, or N/A when no URL applies>
- User: <role or redacted/synthetic alias, never a credential>
- Build/client: <release, client, OS, deployment or UNKNOWN, when useful>

Steps to reproduce:
1. <setup>
2. <action>
3. <result>

Current behavior: <what happens now>
Expected behavior: <what should happen>

API request (cURL), when applicable:
```bash
# Complete redacted curl command: method, URL, headers and body.
```

API response, when applicable:
```http
# Status, headers and body.
```

Database query (read-only), when applicable:
```sql
-- Read-only query.
```

Database result, when applicable:
```text
# Observed result; use its actual format when useful.
```

Evidence, for a UI screenshot or MP4 recording, when applicable: <attach file>
HAR, only when the page-load/request chain matters: <attach file or N/A>

Definition of Done (DoD): <observable regression proof and required checks>
````

`Description`, `ENV:`, `Steps to reproduce`, `Current behavior` and
`Expected behavior` are separate diagnostic fields. `ENV:` keeps the
environment name, exact URL and user used together; its optional `Build/client`
line preserves useful release or client context. Surface-proof sections remain separate
and appear only when applicable. Keep `URL` as `N/A` for a worker, CLI
or other flow with no page to open. Use `UNKNOWN` when the requester does not
know a value; do not replace a missing value with a guess.

Proof must match the affected surface:

- **API:** include a complete redacted `curl` request in one fenced code block
  and the response in a separate fenced `http` block. Keep method, URL, all
  captured headers, body, status and response body; redact sensitive values
  without changing the request's material shape.
- **Database:** include the read-only query and result in separate fenced blocks;
  use `sql` for the query and the result's actual format when useful.
- **UI:** put a screenshot or an MP4 recording in `Evidence`. If the failure
  depends on the page-load/request chain, attach a HAR too; keep the exact URL
  and reproduction steps in the report.

When a bug crosses more than one surface, include each applicable proof pair or
artifact. Do not collapse them into a generic `Evidence` paragraph. A URL or
prose description alone does not replace UI evidence. If required proof is not
supplied, return `INPUT_REQUIRED` and identify what is missing instead of drafting
a report with weaker substitute evidence.

Example:

````text
Title: [Bug] Sync reports success after a provider timeout

Description: A timeout leaves the sync marked as successful.

ENV:
- Name: TEST
- URL: N/A (worker-only reproduction)
- User: sync-test-user
- Build/client: release 1.3.0, local worker, macOS, staging provider

Steps to reproduce:
1. Start a sync against a provider that does not answer.
2. Wait for the request timeout.
3. Open the run history.

Current behavior: The UI shows “success” and no retry is scheduled.
Expected behavior: The run is marked failed or explicitly unknown.

Database query (read-only):
```sql
SELECT status, error FROM sync_runs WHERE id = 42;
```

Database result:
```text
status=success, error=timeout
```

Definition of Done (DoD): A regression test proves timeout is not reported as
success, and any retry behavior in scope is explicitly agreed and covered.
````

Leave the suspected root cause out unless it is verified. A useful bug report
lets another person reproduce the behavior without a meeting. For a defect found
during a DoD check, reproduce it by hand at least once before reporting it: a
failing automated test alone may be a test or data problem.

## ISSUE

Use for a feature, workflow improvement or change request. Keep `Description` to
one sentence, then use only the fields that help someone decide or build it.

```text
Title: [Feature] <user outcome>

Description: <what is hard, missing or unreliable today>
Who is affected: <specific user or workflow>
Desired outcome: <what the user can do or rely on afterwards>
Evidence: <example, frequency, user wording or link>

Acceptance:
- [ ] AC01: <observable pass/fail result>
- [ ] AC02: <observable edge case or failure result>
- [ ] AC03: <proof or compatibility condition, if relevant>

Definition of Done (DoD):
- [ ] <acceptance criteria pass in the affected surface>
- [ ] <required tests/checks and proof are attached or linked>
```

Example:

```text
Title: [Feature] Show why a sync was not retried

Description: A failed run only says “failed”, so it is unclear whether the next
run is safe to start.
Who is affected: Operators checking a failed scheduled sync.
Desired outcome: The run shows whether the failure is retryable and what to do.
Evidence: The current log contains the error, but the run history does not.

Acceptance:
- [ ] AC01: Retryable failures show “retryable” and the next retry time.
- [ ] AC02: Non-retryable failures show “manual action required”.
- [ ] AC03: The existing error detail remains available for diagnosis.

Definition of Done (DoD):
- [ ] The three acceptance criteria pass in the run-history UI.
- [ ] Automated coverage and the verification result are attached to the issue.
```

## USER_STORY

Use the user's goal, not a UI control or implementation task. The familiar
persona/goal/value sentence is useful, but the acceptance criteria decide what
counts as complete.

Derive acceptance from the stated goal. If the source gives only a concern or a
question, keep the criterion at that level and name the missing decision; do not
invent a product policy to make the story look complete. Use `Given/When/Then`
only when it improves verification or matches the team's existing language.

```text
Title: <short user outcome>

Description: <real problem, context or constraint behind the goal>

As a <specific user>, I want <goal> so that <value>.

Context: <real situation or constraint, if needed>
Acceptance:
- AC01: Given <context>, when <action>, then <observable result>.
- AC02: <another independent pass/fail result>

Definition of Done (DoD):
- [ ] <the acceptance criteria pass for the named user>
- [ ] <required tests/checks and proof are attached or linked>

Out of scope: <important boundary, if needed>
```

Example:

```text
Title: Explain failed scheduled syncs

Description: Operators currently see a failed run without knowing whether it is
safe to retry.

As an operator, I want to know whether a failed sync can be retried so that I
do not duplicate data or leave a delivery gap.

Acceptance:
- AC01: Given a timeout, when I open the run, then it is marked retryable and shows
  the next retry time.
- AC02: Given an authentication failure, when I open the run, then it is marked
  “manual action required”.

Definition of Done (DoD):
- [ ] Timeout and authentication scenarios pass in the run-history UI.
- [ ] The verification result is attached and the existing error detail remains
  available.
```

Do not force the `As a / I want / so that` form when the real request is a bug,
decision or operational task. A plain one-sentence outcome is better than a
ceremonial story that hides the need.

## REQUEST

Use for a short ask to a person or team:

```text
Description: <what needs to change or be produced, and why>
Request: <one concrete action>
Why: <one sentence of context>
Input or location: <file, link, example or attachment>
Needed by: <date only when real>
Definition of Done (DoD): <the exact output and proof the requester can verify>
```

Example:

```text
Description: The issue template does not tell reporters what proof is required
for API, database and UI failures.
Request: Update the public bug template with separate copyable proof fields.
Why: Reporters should be able to paste the evidence without reconstructing it.
Input or location: .github/ISSUE_TEMPLATE/bug_report.md
Needed by: 2026-09-02
Definition of Done (DoD): The template has separate request/response, query/result
and UI/HAR fields, and the repository checks confirm their order.
```

## TASK

Use for an automation or QA task, written once before the work starts. It says what
will be delivered. Results go in the completion comment, never back into the task.

```text
Title: <ISSUE-KEY>: <behavior to deliver>

Description: Automate <business behavior> based on <exact requirement link, e.g.
STORY-2 AC01-AC03>.

Acceptance:
- AC01: <flow or context>: <observable behavior and expected outcome>.
- AC02: <flow or context>: <observable behavior and expected outcome>.
- AC03: <negative or compatibility check>: <expected outcome>.

Variants: <roles, locales, platforms or data that must be covered, or none>
Dependencies:
- <TASK-x link>: <what it provides, phrased as a condition>

Definition of Done (DoD):
- [ ] PR reviewed, synced with `<target>`, conflict-free, approved and verified merged.
- [ ] Tests documented in <test case store> and passing on <environment> for the final code.
- [ ] Each AC above is mapped to a test. Gaps are resolved or have a recorded scope decision.
- [ ] Task holds the completion comment with case links, PR link, environment, date and per-test evidence.
- [ ] Parent holds the parent comment with the task link and AC coverage.
- [ ] Task closed after the merge, with the transition read back.
```

Put in the link to the exact requirement, even when it lives in one comment or
section; each scope item as an observable behavior with an expected outcome; and only
the real prerequisites, without claiming "deployed" until that is observed.

Leave out vague scope such as "verify functionality" or "analyse requirements" (do the
analysis first, then write the scope); results, pass counts, SHAs, coverage percentages
and completed-work narrative; and a generic exclusions list. Record an exclusion only
when it is a real scope decision, with a link. Do not widen an agreed task afterwards,
for example by adding "merged" to a handoff-only DoD, without the owner's approval.

Example:

```text
Title: PROJ-512: Automate order approval

Description: Automate purchaser and approver order approval based on
https://tracker.example.test/PROJ-512 AC01-AC02.

Acceptance:
- AC01: Purchaser flow: submitting an order moves it to "awaiting approval".
- AC02: Approver flow: rejecting an order shows the purchaser the rejection reason.

Variants: UK and FR locales
Dependencies:
- PROJ-500: approval feature available on staging

Definition of Done (DoD):
- [ ] PR reviewed, synced with `main`, conflict-free, approved and verified merged.
- [ ] Tests documented in TestRail and passing on staging for the final code.
- [ ] AC01 and AC02 are mapped to tests. Gaps are resolved or have a recorded scope decision.
- [ ] Task holds the completion comment with case links, PR link, environment, date and per-test evidence.
- [ ] Parent holds the parent comment with the task link and AC coverage.
- [ ] Task closed after the merge, with the transition read back.
```

## PR

Use for a pull request title and description. When the repository has its own PR
template, fill that in and use these bullets for its change and verification sections.
Readiness does not go here: the DoD report is a separate text. The exception is a
repository template with its own DoD section, which keeps that section's reviewed head
and statuses.

Title: `<ISSUE-KEY>: <imperative summary of the delivered behavior>`, for example
`PROJ-512: Add order approval tests for purchaser and approver`. Without a ticket, use
`No ticket: <summary>`. Keep it under about 72 characters, with no trailing period.

Indent nested bullets with **four spaces**. Some hosts flatten two-space nesting.

```markdown
**<Sprint>** > **<Team>** > [<EPIC-1>: <epic title>](https://<url>) > [<STORY-2>: <story title>](https://<url>) > [<TASK-3>: <task title>](https://<url>)

- **<Change type>** › [<CASE-ID>: <full case title>](https://<case-url>)
    - [<repo/relative/path.ext>](https://<link-to-file-in-the-PR-source>)
    - <covered endpoint, UI flow or function>; <variant constraint, e.g. "UK and FR only">
- **<Change type>** › <changed capability, e.g. `OrderPage.submitForApproval()`>
    - [<repo/relative/path.ext>](https://<link>)
    - <what changed and why it matters to review>
- **Execution** › [<ENV label>](https://<environment-url>)
    - <Local, CI run link or test-run link> | <Passed or Failed> | <YYYY-MM-DD> | <passed>/<total>
```

Change types: `New test`, `Updated test`, `New feature`, `Fix`, `Refactor`,
`Updated method`, `Tooling`, `Docs`, `Config`.

- Use only the breadcrumb levels that actually exist. Never invent a sprint, team or story.
- One top-level bullet per coherent change. Unrelated changes become separate bullets
  or a separate PR.
- Each environment gets its own execution rows. Dates have no time part. Use `Failed`
  for an observed failure.
- Leave out `N/A` filler, a repeated PR title, SHAs, worker or retry details,
  "screenshot attached" narration and unexecuted placeholders.
- For a docs or tooling PR, the execution rows are the local checks you actually ran
  and their counts.

For a larger PR, add this block only when it helps the reviewer:

```markdown
**Coverage**
- AC01 <short> - `<test name>`
- AC02 <short> - `<test name>`
- AC03 <short> - out of scope, see [decision](https://<url>)

**Risks**
- <risk> - <mitigation or owner>
```

## COMMIT

Use for a commit message. Add no AI or tool attribution lines ("Generated with", AI
co-author trailers).

```text
<ISSUE-KEY>: <imperative summary, under about 72 characters>

<Why the change was needed, in 1-3 lines. Not what the diff already shows.>
```

When merging the target in, use `Merge origin/<target> into <branch>`. Add one line
only if a conflict needed a non-obvious resolution:
`Resolved <file>: kept <side> because <reason>.`

## DELIVERY_COMMENT

Use for a comment on a PR or task while delivering it. Write at most two or three
sentences of prose; links and bullet lists are fine, long explanations, tables and
essays are not. Add no AI or tool attribution lines. Pick one kind.

PR status:

```markdown
DoD: synced with `<target>` (<sha7>), no conflicts. <Env> run <date>: <passed>/<total> passed - [report](https://<url>).
<Only if needed: one sentence on the remaining gap and next action.>
```

```markdown
DoD: not ready. <The gap that matters most, one sentence, with its link.> Next: <one action>.
```

Reply to a review comment:

```markdown
Fixed in <sha7>: <what changed, one sentence>.
```

```markdown
Keeping as is: <reason in one sentence>. <Optional: link to the requirement or prior decision.>
```

```markdown
<One precise question>? <What you will do for each likely answer, if useful.>
```

Completion comment on an automation or QA task:

```markdown
**Coverage**
<1-2 sentences: how the scope was checked and the outcome; name any gap explicitly.>

**Test cases**
- [<CASE-ID>: <exact full case title>](https://<case-url>)

**PR**
- [<PR title>](https://<pr-url>) - <Merged, Open or Approved>

**Environment**
- <YYYY-MM-DD> | <country or locale if relevant> | [<env>](https://<env-url>) | <browser, device or API client if relevant>

**Evidence**
<plain caption>
<attached image: one per executed test or variant, steps readable>
```

- Copy every case ID, title and link from the actual case record. Never type them
  from memory.
- Keep failures and unexecuted scope visible, never only the green parts.
- Keep one authoritative QA comment per task. Update it in place and delete only your
  own superseded duplicates.
- Run links belong in the PR's `Execution` rows. Workers, retries and SHAs belong in
  the private review record, not in this comment.

Parent story or issue, after the merge:

```markdown
Automation for <behavior> merged in [<PR>](https://<url>) and passing on <env> (<date>), task [<TASK-3>](https://<url>).
Covered: <AC01-AC03 or list>. <Only if any: Not covered: <item> - <reason or follow-up link>.>
```

Blocked or partial status on a task or PR:

```markdown
Blocked: <exact blocker> since <date>. Done so far: <scope>. Next action: <one action, owner>.
```

## Human-feel and compression gate

Keep:

- exact product, file, error and user terms;
- the writer's real stance, uncertainty and concrete example;
- one clear ask or next action;
- enough context to reproduce or decide.

Cut:

- greetings, praise and “I would like to kindly…” before the point;
- “improve the experience”, “make it robust” and similar goals without a
  measurable result;
- invented metrics, root causes, personas, urgency or agreement;
- repeated summaries, generic conclusions and implementation detail the reader
  did not request.

Never add mistakes, random slang or fake personal experience to make text seem
human. Naturalness comes from concrete source material and restrained editing.

Before returning, check:

```text
ACTIONABLE: PASS | FAIL
FACTS_TRACEABLE: PASS | FAIL
EXPECTED_OR_DESIRED_CLEAR: PASS | FAIL
ACCEPTANCE_OR_QUESTION_CLEAR: PASS | FAIL | NOT_APPLICABLE
NO_INVENTED_CAUSE_OR_CONTEXT: PASS | FAIL
LOW_VALUE_SENTENCES_REMOVED: PASS | FAIL
```

Return `INPUT_REQUIRED` if a failed check would require invention.

## Research basis

Checked 2026-09-02. These are design inputs, not copied platform templates:

- [GitHub issue and pull request templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) supports reusable guidance and structured issue forms.
- [GitHub issue form configuration](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) shows required fields and separate expected/actual evidence; the public form schema is platform-specific, so this skill remains Markdown-first.
- [GitLab Documentation Style Guide](https://docs.gitlab.com/development/documentation/styleguide/) emphasizes concise, direct, precise, searchable and conversational-but-brief writing.
- [Digital.gov: Writing for understanding](https://digital.gov/guides/plain-language/writing) recommends audience-specific language, short sections and active responsibility.
- [Atlassian: User stories](https://www.atlassian.com/agile/project-management/user-stories) connects persona, goal, value and acceptance criteria; its 3 Cs are Card, Conversation and Confirmation.
- [hannsxpeter/humanizer](https://github.com/hannsxpeter/humanizer/blob/main/SKILL.md) recommends preserving an authentic voice and making minimal edits when the input already sounds human; it explicitly rejects detector gaming.
