Five Principles for Effective Prompts
1. State the objective and success criteria up front
Start with a single sentence that states what you want and how you’ll know it’s right. This gives the agent a clear target and prevents vague reasoning behind the scenes. This is the same principle behind good acceptance criteria in a user story or ticket. “Update the pricing page” is a task title; “Change the monthly price from $99 to $89 and add ‘24/7 support’ to the feature list” is acceptance criteria the agent can actually deliver against.2. Provide concise context with exact sources
Give the minimum context needed and point to precise documents, URLs, or excerpts the agent should use. Name your sources clearly and use formatting to make them easy to parse. Think of this like a creative brief that includes linked assets. You wouldn’t tell a designer “make it look good”—you’d provide the brand guidelines, the copy doc, and the specific images to use. Same principle here.3. Break complex tasks into steps or ask for a plan first
For multi-stage work, request a short plan before execution. This lets the agent clarify ambiguities upfront and ensures you’re aligned before work begins. This mirrors how you’d scope a complex project with a stakeholder—get alignment on the approach before diving into execution. It’s easier to course-correct a plan than a finished deliverable.4. Specify output format, structure, and constraints
Tell the agent exactly how you want the output structured. When working with specific components, include constraints at the component level so the context is applied at the right time. This is like providing a wireframe or template alongside a creative brief. You’re not just saying what content you want—you’re showing where it goes and how it should be formatted.5. Provide examples and edge cases
Agents are excellent at pattern matching. When you provide concrete examples of what you want—especially for edge cases—the agent can recognize and apply those patterns consistently. Think of this like a style guide with “do this, not that” examples. Showing the agent a reference page that demonstrates the right approach is often more effective than describing it in words.Where to Provide Context
Gradial offers multiple levels for providing instructions, from global to task-specific. Use the right level for the right type of guidance.Rules (Global)
Rules apply to every agent across your organization or workspace. Use rules for guidance that genuinely applies everywhere—things like brand voice, terminology standards, or universal formatting requirements. Because rules add context to every task, keep them concise. A rule that tries to do too much will dilute its effectiveness.Folders (Project-level)
Folders are ideal for guidance that applies to a set of related tasks. For page migrations, this is where you’d put general instructions like preferred styles, available patterns, or standard steps to follow.Tasks (Specific)
Task-level instructions are for details unique to that particular piece of work—the specific page, the specific changes, the specific source content. General principle: Start specific at the task level. As you notice patterns in your instructions, promote them to folder-level or rules.Debugging and Troubleshooting
When something doesn’t look right, agents can often debug themselves. A direct follow-up question is frequently the fastest path to understanding what went wrong.Ask the agent directly
If you’re wondering why the agent made a particular decision, just ask:- “Why did you place that content in that component?”
- “The hero isn’t showing in the preview but I see it in the studio. Can you debug and tell me what’s wrong?”
- “Compare this page to [reference page] and identify the gaps.”
Iterative refinement
If the initial result isn’t quite right:- Use follow-up prompts to refine the output, adding specificity as needed
- Once you find instructions that work, consider adding them to future prompts
- If the fix applies broadly, promote it to a rule
Viewing agent actions
Gradial provides tools to see what the agent actually did:- Diff viewer — Compare before and after states to see exactly what changed
- Folder context — View any additional context being passed from the folder level
- Rules panel — See which global and workspace rules are active
- Pattern list — Each run shows which patterns the agent used, including pattern IDs
Common issues
Secondary navigation not working: Try prompting directly: “Please fix the secondary sticky nav so it corresponds to the page content.” Inherited components not updating: Some CMS components inherit from a blueprint and won’t show your changes until inheritance is broken. Prompt with: “Break inheritance on [component name].” Ghost components: When removing items from a list, placeholder components may appear temporarily. These typically disappear once the changes are promoted to production.Context Overload
There’s a balance to how much instruction you provide. Context overload occurs when you give too much information or too many instructions at once—instead of helping, excess context can overwhelm the agent and reduce output quality. This also applies to prolonged activity within a task. Each time the agent runs, all previous output becomes input for the next run, which accumulates context over time. Keep instructions focused. If you find yourself writing a wall of text, consider breaking the work into multiple tasks instead.Getting Help
When submitting a support request, include:- A clear title describing the issue type and symptom (e.g., “Migration: Hero not showing” or “Content Update: Eyebrow text not replaced”)
- A short description of the issue and any debugging steps you’ve already tried
- A link to the task in Gradial
- Screenshots from your CMS editor if relevant, since support may not have direct access to your environment