# Brief a change.

> A good brief comes back as the right CodeHerder pull request the first time. See the five parts it needs and try the composer with real examples.

Source: https://customhosted.com/brief/

№ 01 Brief a change

Every page about the loop says the same sentence: describe what you want, in plain language, and an agent turns it into a pull request. This page is what that sentence means in practice — the five parts a brief actually needs, a composer that assembles them for you, and three real examples of a vague ask turning into one.

№ 02 Anatomy

## Five short answers

None of them are required, but each one you skip is a decision the agent — or whoever reviews the pull request afterward — has to make for you instead.

1. 01 — What you want — An agent builds exactly what is written down, not what was implied by a hallway conversation. — “Add a yearly-billing toggle to the estimator.”
2. 02 — Where it goes — A page, a component, a section — name it, and the agent starts reading the real file instead of guessing at one. — “The estimator on /pricing.”
3. 03 — What must not change — Everything you do not mention is fair game for a careful agent to touch. Naming the guardrail keeps the diff to the one thing you asked for. — “Don't touch the layout — just add the toggle.”
4. 04 — How you'll know it's done — A concrete check gives the person reviewing the pull request something to hold the diff up against, instead of a judgment call. — “Toggling to yearly shows a lower rate than the monthly one.”
5. 05 — How urgent — Says whether this is today's work or next-week's — without it, everything defaults to routine. — “This week — routine.”

№ 03 Compose

## Build your own brief.

Fill in what you know — nothing here is required — and it assembles into the shape above. No account and no network call: the same plain string assembly the estimator already uses for its monthly total.

What you want Where it goes What must not change How you'll know it's done How urgent

Fill in the fields and your brief appears here, ready to copy or send.

№ 04 Worked examples

## Three real ones

Pulled from the case files below — real changes with real outcomes, run through the five questions above.

1. The vague ask — “The site is blinding at night — support dark mode.” — The briefed version — Change brief:
Want: Add a dark theme, switchable from the header.
Where: Site-wide — every page, both nav and footer.
Must not change: Keep it to one palette file; no page should need its own dark-mode CSS.
Done when: A visible toggle flips every page to a dark palette and back, and it remembers the choice.
Urgency: This week — routine — What came back A full day/night theme, auto by default and sticky once a visitor picks a side, everywhere on the site. [See the The site is blinding at night case file →](https://customhosted.com/case-files#cf-01)
2. The vague ask — “Make sure someone on a low-contrast display or a screen reader can actually use this.” — The briefed version — Change brief:
Want: Fix accessibility issues so screen-reader and low-contrast visitors can use the site.
Where: Every route on the site, not just the homepage.
Must not change: Don't change the visual design — fix contrast and structure, not layout.
Done when: An automated accessibility scan of every page passes WCAG 2.1 AA.
Urgency: This week — routine — What came back Site-wide WCAG 2.1 AA contrast and heading-structure fixes, plus an automated crawl that runs against every future change in both themes. [See the Make sure someone on a screen reader can actually use this case file →](https://customhosted.com/case-files#cf-02)
3. The vague ask — “Answer engines should be able to read the whole site, not just the pages we remembered to list.” — The briefed version — Change brief:
Want: Make the whole site readable by answer engines and crawlers, not just search.
Where: Every page currently listed in the sitemap.
Must not change: One list of pages should drive both the human-facing index and the machine one — no second copy to keep in sync by hand.
Done when: A machine-readable index exists, lists every page once, and fails the build if a page is missing from it.
Urgency: Whenever — no deadline — What came back A human directory page and a generated llms.txt, both read from one manifest that cannot fall out of sync with the site. [See the Answer engines should be able to read the whole site case file →](https://customhosted.com/case-files#cf-03)

№ 05 Honestly

## What doesn't belong in a brief

Not every change is this kind of change. Here's what to send somewhere else instead.

- A redesign — Changing the visual system before there is anything to react to needs a plan, not a diff. — Start that as a build with CustomLabs, then bring the iterations here.
- New infrastructure — A second dedicated instance, a new domain, a service that does not exist yet — that changes what is running, not how it behaves. — Send it as a quote request instead, and we will provision it properly.
- A product decision — What to charge, what to build next, whether a feature is worth the maintenance — an agent can carry out a decision, not make it for you. — Make the call, then brief the result.

№ 06 After you send it

## What happens next

Copy the assembled brief, or send it straight over with a quote request — either way it lands as one plain-language ask. An agent reads the live codebase, opens a pull request, and CI and a human review it before anything ships. That whole path, step by step, is the loop — and what happens after the merge, hop by hop, is on [Deploys](https://customhosted.com/deploys).

[See how the loop works →](https://customhosted.com/loop)

№ 07 FAQ

## Brief questions

1. 01 Does someone read this before the agent touches anything? The agent reads the brief, not a person — but nothing it writes reaches production unreviewed. It opens a pull request, and a human approves or sends it back, the same as any other change to the codebase.
2. 02 What if I don't know the answer to one of the five parts? Leave it out. The composer only assembles what you fill in — an agent asked to make a change with no stated guardrail will just use its judgment on the rest of the codebase, the same as a person would.
3. 03 Do I have to use the composer, or can I just write this in the contact form? The composer is a wording aid, not a requirement — if you already know the shape, write it straight into the quote form. Either way ends up in the same place.
4. 04 Is this a support ticket system? No — there's no queue or tracker behind it. It's a form that assembles plain text you copy or send with a quote request; what happens next is described at /loop.

№ 08 See also

## Keep exploring

- [The Loop What happens after a brief lands — the agent, the pull request, the review, the merge.](https://customhosted.com/loop)
- [Environments Where a briefed change is actually seen before it merges — a working URL on staging, not just a diff.](https://customhosted.com/environments)
- [Deploys What happens after the merge — the rest of "that whole path, step by step" below, hop by hop.](https://customhosted.com/deploys)
- [Review What comes back from a brief before the merge — the pull request itself, and how to review it without reading code.](https://customhosted.com/review)
- [Case files The three dossiers above, in full — every step, what review caught, and the real diff stats.](https://customhosted.com/case-files)
- [Onboarding Hour 0 of onboarding is sending a brief like this one, for the first version of the site itself.](https://customhosted.com/onboarding)
- [Iteration — CodeHerder The flat add-on that keeps this loop running after launch — priced on the rate card.](https://customhosted.com/pricing#estimate)
- [Access What the agent that turns this brief into a pull request can and cannot do to your production.](https://customhosted.com/access)
- [Content The most common thing a brief describes — a word, a picture, or a new page.](https://customhosted.com/content)
- [In flight What happens to a brief once it is sent — why one runs at a time, what sets the order, and what slows one down.](https://customhosted.com/in-flight)

## Have a change already in mind?

Compose it above, or skip straight to the quote form — either way you get one fixed monthly rate in writing within a business day.

[Get a quote →](https://customhosted.com/contact)