Cards and card templates
Designing the card so the worker gets a brief rather than a title — fields, checklists, attachments and reusable templates.
The card is the brief. Everything on it reaches the worker that picks it up, so the shape of your cards decides the quality of your runs more than any other single thing.
What a card can hold
- Title and description — the story itself.
- Custom fields can hold a short or long text entry, number, date, dropdown selection, checkbox, web address or email address.
- Priority, assignee, due date, labels and story points.
- Checklists — tasks with their own completion state.
- Attachments — files, images, links.
- Links to other cards — including the card in another workflow that this one was sent to, or came from.
- The discussion — see Discussion.
Edit a story
Open the card, make your changes, and choose Save Changes. The Due date field may appear in the template or under Schedule & estimate. Both positions set the date shown on the timeline. Use Start date and Time estimate to plan the work separately.
If a save is refused, the editor keeps the draft open and shows the reason. For example, if your workspace access changed to read-only, copy any text you need before closing the card. Once you have edit access, you can retry the save.
Add a sketch or image
Select Add a card at the station where the work belongs. Enter a title and choose Draw to sketch directly on the board. Choose Add sketch to save it with the organization's files. For an image already available at a web address, choose GIF / image, paste its URL, and choose Add image. Reopen the card from the board to see the saved image.
Reuse a workflow tag
When creating a story, find Tags and select an existing tag. While editing a story, open Add an existing tag and select its name. For example, applying the same refunds tag to a production incident and its follow-up makes it possible to find both with one tag filter. To remove a tag from one story, choose the remove button beside its name. Other stories keep their copies of the assignment.
To add a new tag while drafting, enter its name, choose a color, then select Create or press Enter in Tag Name. The tag is added to the draft. Select Cancel inside the tag picker to return to the draft. When the story is ready, choose Create Card or press Enter in the story title.
If the story was created and CodeBook reports a problem saving a tag or attachment, keep the dialog open. Once you have write access, choose Retry saving. CodeBook finishes saving to the story it already created. You can reopen that story to check the tags and files.
Card templates
A card template is a reusable card shape, set from the workflow's menu. Build one for the kind of work the workflow carries and the fields stop being optional in practice. (A card template shapes a card. A workflow template sets up a whole assembly line.)
Two examples worth copying:
Bug
Environment (dropdown: production / staging / local) · Browser · Build · Steps to reproduce (long text) · Expected · Actual · Evidence (attachments)
Story
User (who it is for) · Outcome (what changes for them) · Acceptance criteria (long text) · Out of scope · Design reference (link)
A QA agent given the first template can reproduce something. Given a title and a paragraph, it has to guess — and guessing is where the plausible-but-wrong runs come from.
Why fields beat prose
A dropdown with three environments cannot be ambiguous. A sentence saying "it happens on the live site sometimes" can be read four ways, and a worker will pick one.
Fields also make the workflow searchable and filterable, which is what turns a pile of cards into something a person can steer.
Checklists
Checklist items are visible to the worker and are a good way to express "all of these, and say which ones you did". A QA station whose cards carry a checklist of the flows to cover gets reports that walk the list.
Scheduled cards
Open Column options → Recurring Cards, enter the title, choose the destination station and interval, then choose Add recurring card. A weekly dependency audit is one example. Use its switch to pause or resume future card creation. Removing the schedule stops future copies. Existing stories retain their history.
Next
- What the worker reads — exactly what is sent when a run starts.
- Discussion.
Evidence: what was actually checked
"QA passed" is a claim. A card's Evidence shows what the claim rests on, gathered from what each part of CodeBook recorded:
- Pull requests — state, size, what your repository's own checks said, the risk score with its reasons, and the deploy result.
- Commands run on your runner — which command, against which commit, how it ended, and the end of the output when it failed.
- Browser checks — a recording of what the browser did that you can play on the card, each step in words and whether it passed, the page's console errors and failed requests, and the screenshot.
- Reviews — each reviewer's verdict, score and reasons.
- Factory scores — what a scorer gave the run, and why.
- Production — incidents worked on the card.
What was typed into a form field during a browser check is never shown.