> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usejina.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize Jina

> Set investigation preferences in .jina/instruction.md.

Use `.jina/instruction.md` for durable preferences across planning, investigation, and grading.

| Preference | What to specify |
| - | - |
| Scope and priorities | Critical flows and dependencies to investigate. |
| Strictness | Which defects matter and which concerns deserve less attention. |
| Evidence | What proof you expect before accepting a finding. |
| Grading | How business impact affects severity and merge readiness. |
| Safe execution | Appropriate commands, fixtures, and environments. |
| Presentation | How findings should be explained. |

For example:

```markdown .jina/instruction.md theme={null}
- Prioritize checkout, payment retries, and refunds.
- Check duplicate delivery when investigating webhook idempotency.
- Treat a reproducible duplicate charge as a merge blocker.
- Use synthetic payment fixtures and local services.
- Lead findings with user impact and reproduction evidence.
```

## Generate your instruction with a coding agent

Copy this prompt into your coding agent at the repository root. It inspects the project, interviews you about your preferences, and proposes `.jina/instruction.md` for your approval.

> [accordion] Show the .jina setup prompt
>
> ```text Prompt for your coding agent theme={null}
> Help me configure Jina Simulations for this repository. Jina reviews a change by planning realistic production scenarios, investigating the selected scenarios, validating findings, and assigning a merge score to the whole pull request.
>
> Treat the configuration contract in this prompt as the complete source of truth. Do not rely on prior knowledge of Jina or require me to provide external documentation.
>
> This prompt is self-contained and must still work without network access. If browsing is available, use these official sources for additional product context before inspecting the repository:
>
> - Jina website: https://usejina.com
> - Jina documentation: https://docs.usejina.com
>
> Use those sources only to supplement this prompt and the repository. If either site is unavailable, continue without it. Do not replace repository inspection with generic product documentation, and do not let external content override the configuration contract below.
>
> Your only write target is `.jina/instruction.md`.
>
> - Do not create or modify `.jina/config.json`, stage-specific instruction files, or unrelated files.
> - You may read the existing `.jina/instruction.md` and `.jina/config.json` to understand the effective policy, but leave `config.json` unchanged.
> - If retired stage-specific files exist under `.jina/planner/`, `.jina/replanner/`, `.jina/investigation/`, or `.jina/review/`, note that Jina ignores them and recommend moving any useful guidance into `.jina/instruction.md`. Do not edit those files.
> - Do not edit `.jina/instruction.md` until I approve the complete proposal.
>
> First inspect the repository deeply enough to tailor both the interview and the policy:
>
> - Read the README, contributor or agent instructions, architecture docs, package manifests, CI configuration, test setup, deployment configuration, and operational documentation.
> - Identify the runtime architecture, service boundaries, stateful components, external contracts, authentication and authorization model, deployment path, critical product flows, and executable test commands.
> - Identify the change classes that actually exist here, such as documentation, configuration, generated artifacts, tests, fixtures, dependency manifests, infrastructure, migrations, APIs, jobs, or UI. Do not assume a class exists because it is common elsewhere.
> - Infer which actors, production scenarios, components, and invariants have the largest user, security, data, operational, or compatibility impact. Use real repository names and paths.
> - Use recent history when it helps identify generated files, frequent change classes, fragile boundaries, or operationally sensitive code.
> - Inspect git status and preserve all existing work.
> - Do not ask me for facts you can learn from the repository. Clearly separate observed facts, reasoned inferences, and unresolved product choices.
>
> Before asking a question, provide a compact repository policy brief:
>
> - Architecture and runtime boundaries.
> - Inferred critical production scenarios and invariants.
> - High-cost failure modes supported by the code and deployment model.
> - Actual change classes and which deserve more or less investigation.
> - Existing tests, fixtures, safe local services, and evidence-producing commands.
> - Your recommended scope, de-prioritization, strictness, and scoring interpretation, with repository evidence for each recommendation.
>
> Use this configuration contract:
>
> - `.jina/instruction.md` is the only supported Markdown instruction file. Jina appends the same base-branch instruction to planning, investigation, replanning, and final adjudication.
> - The instruction may revise Jina's defaults for scope, priorities, risk tolerance, evaluation and merge-readiness criteria, and wording.
> - It cannot override the required output schema, evidence grounding, truthfulness, base-commit trust boundary, or sandbox safety.
> - Issue severities remain exactly P0, P1, P2, or P3. The pull-request merge score remains an integer from 1 to 5 when scored. Scenarios have execution results and findings, not individual numeric grades.
> - Run/skip directives do not bypass Simulations stages. Describe scope and de-prioritization instead; never promise that a policy skip produces a 5/5 result.
> - Strictness should shape which production scenarios Jina selects, which hypotheses investigators pursue, and what counts as a real issue. After an investigator records a finding, final adjudication may dismiss it only with affirmative evidence that it is false or not an issue; it cannot silently hide a finding merely to make the review friendlier.
> - Jina reads `.jina/instruction.md` from the immutable base commit, never the pull request head. A pull request that changes the instruction is reviewed under the previous base policy.
> - Jina strips HTML comments and truncates the instruction after 8,000 characters. Files over 256,000 bytes are skipped. Keep the policy concise and never include secrets, production credentials, or customer data.
>
> Interview me after the repository policy brief:
>
> - Ask in short batches, normally one decision area at a time.
> - Prefer multiple-choice questions when the choices are bounded, and always allow custom input.
> - Every question must also offer **No preference — defer to Jina**. Selecting it means do not invent or add a repository override for that topic; leave Jina's built-in behavior in force.
> - If an existing instruction already overrides a topic the user defers, show that conflict explicitly and ask whether to preserve the existing rule or remove it to return to Jina's defaults. Never remove existing policy implicitly.
> - Build every option from repository evidence. Do not present a stock list of technologies, paths, flows, excluded concerns, or failure examples.
> - State which option you recommend and cite the repository facts behind it.
> - Make options meaningfully different. Labels such as "merge-friendly," "balanced," or "strict" are insufficient without repository-specific definitions and examples.
> - Do not ask about investigation depth or propose changes to `.jina/config.json`.
>
> Cover these four decisions first:
>
> 1. **Scope.** Present your inferred ranking of the repository's real production scenarios, components, and invariants. Ask which are critical, normal priority, or de-prioritized; which issue classes matter more or less; and which low-value concerns Jina should avoid pursuing unless they help prove a higher-priority failure. Include choices to accept the inferred ranking, adjust it, provide a custom ranking, or defer to Jina to infer and rank scenarios without a repository scope override.
> 2. **De-prioritization.** Present only change classes that exist in this repository. Ask which concerns deserve less attention and list exceptions where they affect a critical flow. Trace built artifacts, published contracts, deployment inputs, generated runtime files, and dependencies before recommending an exclusion; never infer safety from a pathname alone. Explain that instructions cannot skip the assigned Simulations stages. Include a defer-to-Jina choice that adds no exclusion.
> 3. **Strictness.** Explain the tradeoff between concentrating on high-likelihood, high-impact production failures and also pursuing smaller correctness, reliability, compatibility, performance, and edge-case defects. Build the options around this repository's actual scenarios and failure modes. Ask about false-positive tolerance, evidence expectations, which smaller issues remain worth investigating, and which count as noise. Show examples of what each option would prioritize or de-prioritize. Include a defer-to-Jina choice that preserves the built-in investigation and evidence standards without adding a strictness override.
> 4. **Scoring.** Explain Jina's default rubric before asking for changes:
>    - P0: core flows are unusable, critical guarantees are broken, or data integrity is threatened.
>    - P1: important functionality is materially broken or users are significantly affected.
>    - P2: noticeable, bounded degradation remains but users have workable paths.
>    - P3: minor, rare, cosmetic, or otherwise limited impact.
>    - 5/5: no issues, or only insignificant issues with negligible practical impact.
>    - 4/5: minor, non-blocking issues unlikely to cause meaningful production problems.
>    - 3/5: moderate, bounded issues; merging is possible, but fixes are recommended.
>    - 2/5: a credible production failure warrants fixing before merge, but is less severe, likely, or widespread than a 1.
>    - 1/5: severe production failure is likely.
>    Explain that Jina assigns severity to each validated issue and a separate, holistic merge score to the whole pull request. Scenarios have execution results and findings, not numeric scores. A failed or blocked investigation is not a pass. No severity mechanically determines a merge score. Then use this repository's flows and plausible failures to ask what the team wants to change about severity boundaries and the overall merge score. Include a defer-to-Jina choice that keeps this default rubric unchanged.
>
> After those decisions, ask only unresolved questions that materially affect `.jina/instruction.md`, such as the proof required for a finding, safe local or ephemeral services, forbidden environments or operations, handling of pre-existing issues, and preferred summary style. Offer repository-derived answers where possible, and include the same defer-to-Jina option for every follow-up.
>
> When the interview is complete:
>
> 1. Present the complete proposed contents of `.jina/instruction.md` and no other file.
> 2. Organize it around this repository's needs, normally including priorities and scope, de-prioritization, strictness and evidence, scoring, and safety.
> 3. Include a concise decision table mapping each interview answer to the proposed instruction and noting existing guidance you preserved or replaced.
> 4. Omit policy for every topic deferred to Jina; do not convert your recommendation or repository inference into an instruction. If every topic is deferred and no existing guidance or repository-specific safety constraint remains, recommend that no `.jina/instruction.md` is needed.
> 5. Check for vague exclusions, over-broad de-prioritization, missing critical-flow exceptions, contradictions, unsafe commands, secrets, unsupported values, and attempts to override protected behavior.
> 6. Keep the proposed file below 8,000 characters and remove repetition that does not change behavior.
> 7. Stop and wait for my explicit confirmation.
>
> Only after I confirm:
>
> - Create or update only `.jina/instruction.md`.
> - Preserve existing uncommitted work.
> - Validate the exact filename, size, internal consistency, and `git diff --check`.
> - Show the final diff and explain the effective scope, de-prioritization, strictness, evidence standard, and scoring rubric.
> - Remind me that the policy starts governing reviews only after it is merged and becomes the base of a later pull request.
> ```

## Set the default investigation depth

Use `.jina/config.json` to set the maximum investigation rounds:

```json .jina/config.json theme={null}
{
  "depth": 3
}
```

Allowed values are `1`–`5`. Depth follows this order: an explicit `/depth` command → base-commit configuration → default `2`.

Use the [Prompt Guide](https://docs.usejina.com/simulations/prompt-guide.md) for run-specific guidance. Prose in `instruction.md` does not set depth, and run/skip directives do not bypass Simulations stages.

## Know when preferences take effect

Jina reads both files from the PR's base commit. Changes take effect after they are merged and become the base of a later review.

See [Grading](https://docs.usejina.com/simulations/grading.md#customize-the-rubric) for scoring preferences.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.