🧠 Custom agent instructions

Teach SiftPulse your codebase's conventions, stack, and priorities. Custom instructions are prepended to the agent's system prompt so every PR review and issue triage speaks your team's language.

Why it matters: Generic AI review flags ORM choices and missing error handling patterns that are fine in your stack. With custom instructions, the agent knows you use Drizzle not Prisma, that wrapErr() is your error convention, and that auth bugs are always P1.

Dashboard (quickest way)

Open your dashboard.
Scroll to 🧠 Custom agent instructions.
Expand the repo you want to tune.
Fill in "Custom PR review instructions" and/or "Custom issue triage instructions".
Click Save instructions. Takes effect on the next PR or issue.

Repos appear in the list once they have at least one agent activity event (a PR review or triage run). Dashboard settings are stored per-repo and apply to all future agent runs.

.siftpulse.yml (recommended for teams)

Commit instructions to your repo under .siftpulse.yml. This makes your agent configuration version-controlled and reviewable. YAML always wins over dashboard settings when both are set.

# .siftpulse.yml — SiftPulse per-repo configuration

# PR Review agent: prepended verbatim before the system prompt
review_prompt: |
  We use Drizzle ORM — never suggest Prisma, Sequelize, or TypeORM.
  All async functions must use our wrapErr() pattern for error handling.
  Flag missing OpenTelemetry spans on any new route or background job.
  Auth and payment paths require unit tests — flag PRs that lack them as blockers.

# Issue triage agent: prepended verbatim before the system prompt
triage_prompt: |
  Auth and payment bugs are always high priority, even if vaguely described.
  Our P1 SLA is 4 hours — use critical priority for anything that blocks checkout.
  Issues tagged "security" should always be assigned to @security-team.

# Structured coding conventions (validated, deterministic — see below)
conventions: |
  forbidden_libs:
    - prisma
    - sequelize
  error_pattern: result
  test_required_for:
    - auth
    - payments

Key	What it does	Max length
review_prompt	Prepended to the PR Review agent's system message on every review (initial and incremental)	2000 chars
triage_prompt	Prepended to the Issue Triage agent's system message on every triage run	2000 chars

Priority rule: If you set instructions in both YAML and the dashboard, YAML wins. The winning source is logged on each agent run so you can debug unexpected behaviour.

Structured coding conventions

For rules you want enforced deterministically — "we use Drizzle, never Prisma", "auth paths require tests", "our error pattern is Result<T,E>" — use the structured conventions block instead of freeform prose. Conventions are validated against a fixed schema, serialized to JSON, and rendered as a deterministic ## Team Coding Conventions section in front of the agent's system prompt. They take priority over freeform guidance so a vague prose rule can't accidentally override an explicit one.

# .siftpulse.yml
conventions: |
  forbidden_libs:
    - prisma
    - sequelize
  required_libs:
    - drizzle
  error_pattern: result
  naming_files: kebab
  naming_vars: camel
  test_required_for:
    - auth
    - payments
  observability: otel
  severity_overrides:
    - category: Security
      severity: blocker
    - category: Performance
      severity: suggestion
  block_substring_in_diff:
    - TODO
    - FIXME
    - console.log

Key	Type	Example
forbidden_libs	string[]	`prisma, sequelize`
required_libs	string[]	`drizzle, otel`
error_pattern	enum	`result \| throws \| callback`
naming_files	enum	`kebab \| snake \| camel \| pascal`
naming_vars	enum	`camel \| snake`
test_required_for	string[]	`auth, payments`
observability	enum	`otel \| datadog \| none`
severity_overrides	{category, severity}[]	`{Security: blocker}`
block_substring_in_diff	string[]	`TODO, FIXME, console.log`

YAML wins, like freeform prompts. If a conventions block is in .siftpulse.yml, the dashboard values are overridden. The winning source is logged on each agent run — [custom-prompts] repo — source: yaml (conventions only) when only a YAML conventions block is set, or source: yaml when freeform fields are also set. custom_prompt_applied flips to true whenever either source is set.

What good instructions look like

Stack specifics — "We use Remix, not Next.js. Never suggest Next.js patterns."
Error conventions — "All errors must go through our AppError class."
Observability requirements — "Every new route needs a DataDog span."
Test policy — "Any function touching payments requires a unit test."
Priority rules — "Any issue mentioning 'checkout' or 'billing' is at least high."
Ownership hints — "Database migrations always need a senior review."

Observability

Every PR review and triage event logs a custom_prompt_applied flag. When instructions are active, it's true — visible in your database for debugging and future reporting. Support can reference this when investigating why the agent flagged something unexpected.

FAQ

Will instructions override the agent's built-in quality checks?

No. Instructions are prepended before the system prompt, so the agent still applies its default review criteria. Your instructions add context — they don't remove built-in checks.

How long does it take to apply?

Immediately. The next PR or issue after saving will use the new instructions.

Can I set different instructions per branch or environment?

Not yet — instructions are per-repo. If you need branch-level control, open a feature request.