Best practices

Hydra works best when you treat each session like a focused work order — not an endless thread. These habits keep context sharp, plans accurate, and credit spend predictable.

Quick checklist

#	Habit	Why
1	One task per chat session	Smaller context = sharper answers and fewer missed steps
2	Start a new chat after a big build	Post-build history bloats the window and dilutes follow-ups
3	Use CTX on the right desk page	Hydra sees the DocType, form, or list you're actually working on
4	Attach specs, screenshots, and PDFs	Rich input beats vague "make it like the old system"
5	Plan big work outside, implement inside	Draft the PRD elsewhere; attach it when you're ready to build
6	Default to Plan mode	Review before Proceed — especially for multi-step work
7	Run on dev or sandbox	Never point Hydra at production — see Is it safe?

---

One task per session

Don't stack unrelated prompts in a single chat. Each message resends the full conversation history. The longer the thread, the more noise Hydra carries — and the easier it is to lose focus on what matters now.

Do

• One clear goal per session — e.g. "Add a Region custom field to Customer" or "Build the purchase approval workflow, steps 1–3."
• Break large work into sub-tasks — finish one piece, verify it, then open New chat (⌘⌥N) for the next.
• Start fresh after a major plan execution — once Hydra completes a full build and you get Changes Made, treat that chat as done. Follow-ups belong in a new session with a tight brief.

Avoid

• Chaining "also fix the print format" → "and add a dashboard" → "oh and migrate the old data" in the same thread.
• Using one marathon session as a scratchpad for the whole project.

flowchart LR
  A[New chat] --> B[Single focused task]
  B --> C[Review plan → Proceed]
  C --> D[Verify Changes Made]
  D --> E{More work?}
  E -->|Yes| F[New chat — next sub-task]
  E -->|No| G[Export via Custom Migrator]
  F --> B

Rule of thumb: If the task has a different acceptance criterion, it probably deserves a new chat.

---

Pass better context with CTX

Hydra can see your current Frappe Desk screen — but only if you give it that context.

Use CTX on the right page

Before you ask, navigate to the record or DocType your task is about, then press CTX in the Hydra panel. Hydra receives the full details of that desk page — fields, layout, linked DocTypes, and related metadata.

Your task	Be on this page first	Then
Modify Sales Invoice	Sales Invoice list or form	Open Hydra → CTX → describe the change
Create a Print Format	Print Format list or the target DocType	CTX → attach a sample PDF if you have one
Add a custom field	The target DocType form	CTX → specify field name, type, and behaviour
Fix a workflow	Workflow list or the linked DocType	CTX → describe the transition or state change

CTX beats guessing. "Add a field to this form" with CTX active is far more reliable than describing a DocType from memory three screens away.

Attach files when they help

Use Attach a file for anything Hydra can't infer from the screen alone:

• Screenshots of a legacy system, mockup, or error message
• PDFs — process docs, approval matrices, form layouts
• Spreadsheets — sample data, field mappings, import templates
• Markdown specs — PRDs, task lists, acceptance criteria (see below)

Hydra reads attachments directly. Combine CTX + attachment when the screen shows where the change lives and the file shows what it should look like.

---

Plan big work outside Hydra

For large features — multi-step workflows, new modules, cross-doctype integrations — brainstorm and structure the plan before you open Hydra to build.

The external PRD workflow

1. Draft elsewhere — Cursor, ChatGPT, a wiki doc, or a whiteboard session with your BA team.
2. Write a PRD as Markdown — requirements, edge cases, task breakdown, and acceptance criteria per task.
3. Attach the MD file in Hydra — open a fresh chat, attach the plan, switch to Plan mode, and ask Hydra to implement task 1 (or the first phase).
4. Execute in phases — one session per phase or task group. Don't dump a 40-item checklist into a single thread.

Example PRD structure:

# Purchase Approval Workflow

## Goal
Three-level approval for POs over $10k.

## Tasks
1. Create Approval Level DocType
2. Add custom fields to Purchase Order
3. Server Script: validate hierarchy on submit
4. Workflow: Pending → L1 → L2 → L3 → Approved
5. Email notification on each level

## Acceptance
- PO under $10k skips L2/L3
- Rejection returns to draft with comment

Attach this file, then prompt: "Implement tasks 1–3 from the attached PRD. Show me the plan before building."

When the context window feels heavy

If Hydra's responses get vague, plans start skipping steps, or follow-ups reference the wrong earlier work — stop and split:

• Close the chat (it's saved under Past chats if you need it).
• Open New chat with only the next sub-task and any files it needs.
• Reference completed work by name ("Approval Level DocType already exists — now add the PO custom fields") instead of relying on thread history.

---

Write prompts that build well

Beyond session hygiene, how you ask still matters.

Do	Avoid
"When a Sales Invoice is submitted, email the customer's account manager"	"Fix invoicing"
Name the DocType, trigger, and outcome	Assume Hydra knows your org chart
One change per prompt inside a session	Mix unrelated requests in one message
Plan mode for anything that creates or edits config	Fast mode for a quick script you already understand

In Plan mode, use Modify plan if the steps aren't right — cheaper than undoing a bad build. Download Plan before Proceed on large work so your team has a record.

---

After the build

Hydra finishes on your dev site. The handoff to production is separate:

1. Verify — open the links in Changes Made and test the flow manually.
2. Export — use Custom Migrator to push changes to Git with a diff preview.
3. Ship — promote through Espresso Cloud dev → staging → production.

Don't ask Hydra to "also deploy to production" — that's what Espresso and Custom Migrator are for.

---

Credits and modes

What you do	Typical cost	Best practice
Ask a question	~2 credits	Use Ask + CTX — read-only, safe to explore
Full plan + build	~15 credits	One focused task; don't burn a build on vague scope
Fast script	~5 credits	Only when scope is tiny and you skip the plan step

Hydra pauses at your credit limit — no overage. Splitting work across sessions also spreads cost across the month instead of one expensive mega-thread.

---

Next

• Working with Hydra — panel, modes, and reviewing a plan
• Is it safe? — dev sites, approval, and logging
• FAQ & troubleshooting