Good vs. Bad Instructions

Good Approach

<Check>
  "Create a new endpoint `/users/stats` that returns a JSON object with user count and average signup age. Use our existing users table in PostgreSQL. You can reference the `/orders/stats` endpoint in `statsController.js` for how we structure responses. Ensure the new endpoint is covered by the `StatsController.test.js` suite."
</Check>

Why This Works:

Clearly specifies the route and expected response format
References existing code as a template
Defines data source (users table)
Includes test coverage requirements

<br />

<br />
Bad Approach
<Warning>
  "Add a user stats endpoint."
</Warning>
Why This Fails:

Unspecific about what stats to include
No mention of data sources
No reference to existing patterns
Missing test requirements

Good Approach

<Check>
  "Draft a one-page diligence summary for Acme Corp. Pull the last three years of financials from the connected Drive folder `/deals/acme/`, cross-check the revenue figures against the Acme opportunity record in the CRM, and follow the `diligence-memo` playbook for structure. Flag any discrepancy over 5%, cite each source, and save the memo to the Acme deal workspace."
</Check>

Why This Works:

Names the exact sources (Drive folder and CRM record)
Defines the deliverable (a one-page memo) and where it goes
References a playbook as a template
Sets a clear validation rule (flag discrepancies over 5%, cite sources)

<br />

<br />
Bad Approach
<Warning>
  "Look into Acme and tell me if it's a good deal."
</Warning>
Why This Fails:

"Good deal" is subjective with no criteria
No sources of record specified
Unclear deliverable and format
No verification or citation requirement

**Why Good?** Clear success metric (80% coverage), references to guide Opulent (`UserService.test.js`), and a well-defined scope with specific verification steps.

**Why Good?** There's a clear template (`tsconfig.json`) and test suite for immediate feedback, plus specific compilation and validation steps.

**Why Good?** Names the source of record (CRM + ledger), reuses a playbook, defines the exact output, and requires Opulent to cross-check the numbers before delivering.

**Why Good?** Links the specific Figma file, names the exact frame, references the project's design system and existing components, and tells Opulent to visually verify its work before opening a PR. With the [Figma connector](/work-with-opulent/connector-marketplace) connected, Opulent can read design tokens directly from the file.

**Why Good?** Points Opulent to the right tools ([connectors](/work-with-opulent/connector-marketplace)), gives a clear investigation path, and defines the expected deliverable (fix + regression test + PR).

**Why Bad?** The request is too vague and open-ended. There are no success criteria and no way for Opulent to know when it's done.

**Instead:** Use [Opulent Review](/work-with-opulent/opulent-review) for automated code review on specific PRs, or give Opulent a targeted task like "Find and fix all uses of the deprecated `oldLogger` API in `src/services/`."

**Why Bad?** "Better" is subjective and Opulent has no criteria to aim for. Opulent can build functional UIs and implement designs from specs, but it can't make aesthetic judgment calls on its own — the same is true for "make this report nicer" without a target format.

**Instead:** Provide a Figma design, a reference site, or specific changes: "Increase the hero section font size to 48px, add 32px padding, and use the `indigo-500` color from our Tailwind config."

**Why Bad?** This is a very large and unstructured task. It requires many architectural decisions, trade-offs, and context that isn't in the prompt.

**Instead, break it down:**

1. Use [Ask Opulent](/work-with-opulent/ask-opulent) (a product target) to investigate your workspace and map dependencies
2. Ask Opulent to propose specific architectures with trade-offs
3. Create separate sessions for implementing each service — run them in parallel with [managed agents](/work-with-opulent/handoff-and-managed-agents)