Writing Trello Cards That Developers Actually Understand

Practical tips from decades in the trenches of software delivery

If you’ve ever worked on a software project, you’ve probably seen it happen: a Trello card comes in, but the description is vague, the requirements are fuzzy, and the developers spend more time asking questions than writing code.

At Gnomon Technology, we’ve made it a point to fight that problem head-on. Clear, well-written Trello cards save time, reduce rework, and keep relationships between teams and clients strong.

Recently, I sat down with my co-founder Robert to talk about the way he structures cards. Robert has been in the software world for over 30 years, and he’s built a repeatable, field-tested system that works for everything from fixing bugs to defining big new features.

The best part? You can start using it today.

The Bug Card Format

“Bug cards are emotional by nature,” Robert said. “Something’s broken, the team is stressed, and the business is upset. We need to write in a way that diffuses anxiety and stays rooted in facts.”

His bug card format is short, simple, and incredibly effective:

• Situation – What should be happening (expectation) right now in the system?
• Complication – What’s broken (actually happening) or behaving incorrectly?
• Resolution – What needs to change to fix the issue?

This three-part structure gives developers exactly what they need to reproduce the bug and fix it without wading through speculation or frustration. Here's an example:

• Situation: I can view inventory reorder details when clicked from the dashboard.
• Complication: The resulting modal window shows the wrong medication ID, pulling data from a previous session.
• Resolution: The modal should pull the current item ID from the selected row in the inventory table. Prior session cache should not persist.

“Don’t editorialize. Don’t speculate. Just describe what is, and what should be,” Robert said.

“You’re writing the recipe the devs will follow,” Robert told me. “If your card isn’t specific, you’ll get something undercooked, missing ingredients, or seasoned wrong. That’s on us.”

The New Requirement Format

This format is best used for new (raw) requirements. That is, you are implementing a feature that does not currently exist. Here's an example:

1. Description
Every raw requirements card begins with a clear description — a short but complete explanation of the business context. This section should answer three questions: What problem are we solving? Who is the feature for? And what is the value to the business? Robert always writes it in plain language so that even someone on the client’s side who doesn’t speak tech can understand it. For example, a card might open with: Pharmacy managers need a way to track medication inventory in real time to prevent stockouts and overordering. This feature will allow them to set reorder thresholds, view current stock, and initiate restocking workflows.

2. Prerequisites
Next, he identifies the conditions that must already be in place before the feature to produce the desired result. If these aren’t met, the system must not allow the user (or itself) to initiate the feature. This might include having a security privilege provisioned, ensuring that inventory records exist in the database, or confirming that the user is authenticated as a pharmacy manager. Calling out prerequisites upfront reduces the need for exception handling and complex error messaging.

3. Requirements
This is the heart of the card, the detailed description of what the feature should do. Robert phrases each requirement as a discrete, testable behavior, starting with a verb and keeping the order logical. Instead of a vague sentence like “The user should be able to change reorder thresholds,” he writes “Allow editing of reorder thresholds inline.” Other examples might include “Display inventory table with sortable columns” or “Highlight any row in red where quantity is less than the threshold.”

A great requirement isn’t limited to “blue sky” (perfect conditions) scenarios. In fact, only 20% of this section should cover the ideal. The other 80% should cover exception handling. Without good exception handling, users (and the system itself) will run into unhandled situations resulting in generic error messages.

4. Acceptance Criteria
Once requirements are laid out, Robert defines the acceptance criteria, QA’s checklist and the definition of done. These criteria might specify that a manager can update reorder thresholds and save without error, that red highlights appear instantly when the threshold is breached, or that clicking “Reorder” opens a modal with accurate item data. The goal is to make each criterion binary: it either works, or it doesn’t.

5. Limitations
This section sets clear boundaries and helps prevent scope creep. Here Robert states what will not be included in the current sprint, even if the client has requested it. For example, vendor integration for auto-ordering might be out of scope, PDF export may not be included in this release, or the inventory audit trail might be postponed to a future sprint. Limiting scope like this helps teams deliver on time without overpromising.

6. Optional: Technical Notes / Schema
Finally, Robert sometimes adds technical notes or a database schema (ER diagram) to give developers a head start. Even a quick outline of a database table, such as an InventoryItem with fields for id, drug_name, quantity, expiration_date, and reorder_threshold, can save time, align expectations, and prevent miscommunication between technical and non-technical team members.

Why This Works

• This approach works because it strikes the right balance between context and precision.
• Context ensures developers understand the “why” behind a feature.
• Precision ensures they know exactly what to build and how it should behave.

When cards are written this way, developers can go heads-down and build with confidence. When they’re vague, everything stops and spins.

Your Turn

Robert’s framework has become our gold standard at Gnomon Technology, but it’s flexible enough for any team. Try it on your next card, tweak it to fit your process, and watch how much smoother your dev cycles run.