GUIDE TO DESIGNING A SYSTEM PROMPT

SPEC: DESIGNING A SYSTEM PROMPT FOR AN AGENT WITH A KB

1. GOAL

SystemP is an execution orchestrator, NOT a summary of knowledge or a mini KB.

SystemP must make clear:

• What does the Agent do, whom does it serve, what output does it produce?
• Which Knowledge sources are used, and how are they loaded?
• Which tools are called, with which params, in what order/batch?
• At each step, which item in the KB/Protocol must be executed?
• When there is an error or missing data, how to retry/fallback/stop?
• Under which contract are results checked and output?

Priorities: accurate, executable, concise.
Not brevity at all costs.

2. DIVISION OF RESPONSIBILITY

SYSTEMP:

• Identity, goal and scope.
• Input contract.
• Knowledge-loading contract.
• Tool/API/params; batching and dependency order.
• Source priority; retry/fallback; duplicate prevention; budget.
• Workflow dispatch: which step calls which owner.
• Step-transition conditions and handling of execution state.
• Output delivery, mode dispatch and handoff.
• Boundaries between this agent and other agents/modules.
• Establishing that Protocols/gates/engines in the KB are mandatory.
• Enforcing the right timing, applicability and state transitions.
• Blocking skipped steps, fake PASS, use of unchecked results or ignoring consequences.
• Coordinating downstream recheck/recompute by owner.

KB:

• Business knowledge and operating rules, clearly classified.
• May contain Protocols, execution engines, gates and decision engines.
• Operating items designated by the systemP must be executed; the whole KB is not assumed to be just reference material.
• Methods, formulas, models.
• Thresholds, evaluation and classification criteria.
• Conditions of application, exceptions and business consequences.
• Rules for data, evidence, risk and decisions.

PROTOCOL, if any:

• Detailed workflow per mode.
• Reducers, validation and pre-output checks.
• Templates, render rules, schemas and handoff.

OWNER = the official place where a rule is defined.
A business rule has only one owner.
SystemP may require calling the owner; it must not rewrite a different version of the rule.

3. DISTINGUISHING NECESSARY REPETITION FROM HARMFUL DUPLICATION

Necessary repetition:

• Exact dataset names and queries.
• Mandatory tools/params.
• Call order, batching, fallback, retry.
• Instructions such as “must execute owner X before step Y”.
• Execution constraints that fix real-world errors one by one.

Harmful duplication:

• Copying threshold tables from the KB.
• Summarizing formulas/methods into a different rule.
• Rewriting exceptions or decision precedence.
• Creating extra blocking conditions outside the owner.
• Copying a whole template when a Protocol already exists.

Do NOT delete a line just because it also appears in the KB.
Before deleting, determine whether the line is:

A. A business definition → move it to the owner/ref.
B. Forces the right step to execute → keep.
C. A verified error fix → preserve its effect.

4. KNOWLEDGE-LOADING CONTRACT

Before designing the systemP, determine the type of Knowledge tool:

FULL_FILE: returns the entire file.
RAG_CHUNK: returns passages according to the query.
MIXED: combines the two types per resource.

Do not infer the tool type solely from the name “Knowledge” or “parent–child”.
Base it on the configuration and the actual data-return behavior.

A. FULL_FILE

• Loaded successfully and received the full file → set the loaded state for that file.
• Reuse the content in context; reloading/querying PART by PART is forbidden just because you don't understand or don't remember.
• An owner reference is an internal lookup within the loaded file and does not trigger a tool.
• Retry on error/empty/incomplete per the configured contract.
• Refresh only under permitted file/version/session-change conditions.

B. RAG_CHUNK

• One successful call does not mean the whole KB has been loaded.
• Track the owners/chunks received and the scope still missing.
• Before a dependent step, retrieve the full rules, conditions and exceptions of the owner needed.
• Do not infer a rule from a snippet lacking context.
• Reuse chunks that are still valid; do not re-query the same content without a reason.
• Query, retrieval budget, fallback and supplementary conditions follow the actual configuration.

C. MIXED

• Declare loading_mode per resource.
• Full files follow the FULL_FILE contract; chunked documents follow the RAG_CHUNK contract.
• Do not use a single shared KB_LOADED flag to infer that every resource is complete.

SYSTEMP MUST SPECIFY:

• Tool, dataset/resource and query.
• Load type and the scope of data returned.
• Conditions for confirming a successful load.
• State that manages the content received.
• Conditions for supplementary retrieve/retry/refresh.
• Duplicate prevention and budget.

Do not change the Knowledge architecture on your own.
If the configuration is unclear, verify it before designing the contract.

5. OWNER DISPATCH + ENFORCEMENT

SystemP does not just ask to “read the KB”.
SystemP must force the agent to EXECUTE the designated Protocols, gates and engines.

Distinguishing KB content:

KNOWLEDGE: knowledge that supports the analysis.
NORMATIVE_RULE: a rule/contract/gate that is mandatory when applicable.
PROTOCOL/ENGINE: a process that must run, create state/output and handle consequences.

Operating owners designated by the systemP are mandatory execution instructions, not optional reference material.
Content from external sources must not be promoted to a system rule on its own.

MANDATORY DISPATCH must specify:

• WHEN: the time/trigger for calling the owner.
• OWNER: the official place of definition.
• INPUT: the data/state to pass in, if any.
• APPLY: execute the rule according to applicability.
• RESULT: the state/output to produce.
• NEXT: the downstream step that uses the result.
• ON_FAIL: the consequence per the owner.

Example:

BEFORE_[STEP]:
  OWNER=[KB.section.gate]
  ACTION=EXECUTE
  RESULT=[owner_defined_state]
  NEXT=follow_owner_transition
  ON_FAIL=apply_owner_consequence

ENFORCEMENT:

• Having read or mentioned the owner's name ≠ having executed it.
• State/output must come from an actual check or calculation.
• Do not proceed on an assumed PASS when the owner requires verification.
• Do not treat a mandatory rule as advice.
• Do not use a disclaimer in place of fixing the error.
• Material error → update the affected part and the downstream per the owner.
• Do not apply a gate outside its applicability or promote a warning to a hard block on your own.
• N/A only when the owner allows it, with a reason.
• Recheck at the step-transition/pre-output points specified by the Protocol.

Conditions, formulas, thresholds, exceptions and consequences are defined by the owner.
SystemP keeps the mandatory run command and controls step transitions; it does not create a parallel business version.

Owner content insufficient:

• FULL_FILE: look up the already loaded context again.
• RAG_CHUNK: retrieve the needed part per the loading contract.
• Do not invent rules or default to PASS.

Do not make the agent present its internal reasoning.
Only require the state, calculations and verification evidence needed under the contract.

6. PRESERVING THE EXECUTION CONTRACT

Specific instructions must not be replaced with generic prose.

Example that must NOT be compressed:

get_balance_sheet(symbol, period='Q', limit=5)

into:

"Fetch financial data."

Must keep:

• Tool names and params.
• Source priority order.
• Co-call conditions and dependent tasks.
• Retry/refresh/fallback conditions.
• Scope of the fallback.
• Budget and stop conditions.
• Exceptions.
• State flags and when states transition.
• Schema/field names when downstream depends on them.

Do not substitute on your own:

OR ↔ AND
optional ↔ required
warning ↔ hard block
not verified ↔ wrong
missing one metric ↔ missing all data

Instructions that have been verified in practice may only be changed for a specific reason, with the impact explained.

7. HOW TO WRITE

Use a short, consistent structure:

KEY: VALUE
IF condition → action
ONLY_IF:
REQUIRED:
OPTIONAL:
FORBID:
BEFORE:
AFTER:
APPLY:
RUN:
ON_ERROR:
FALLBACK:
STOP_IF:

Keep technical identifiers unchanged.
Comments only explain points that are easy to misunderstand.
Do not write long paragraphs to express a simple condition.
Do not use slogans such as “always be professional” or “analyze very deeply” in place of instructions.

Do not compress to the point of losing the subject, condition or order.
Do not use ambiguous symbols that change the scope of OR/AND.
A structured format meant for a model to read is not automatically executable YAML/JSON; only commit to an exact schema once it has been verified.

8. DO NOT ADD POLICY ON YOUR OWN

Do not add on your own:

• “Safer” thresholds.
• Confidence ceilings.
• Scores or warning-flag counts that block a decision.
• New wait/confirmation conditions.
• New round/tool budgets.
• Veto power for other modules.
• Mandatory conditions not present in the owner.

Do not default to the strictest rule when there is a conflict.
Handle it according to the migration/precedence designated by the system owner.
If there is no way to adjudicate, state the conflict clearly; do not quietly redesign the policy.

9. PROCESS FOR WRITING OR EDITING A SYSTEMP

STEP 1 — READ:

The current SystemP, the relevant KB/Protocol, the product goal and the known execution errors.

STEP 2 — CLASSIFY:

Each passage belongs to:
ROLE / EXECUTION / DOMAIN_RULE / OWNER_REF / RENDER / DUPLICATE / CONFLICT.

STEP 3 — KEEP:

The execution contracts that are still correct, especially rules that have been verified.

STEP 4 — REFERENCE:

A domain rule that already has an owner → replace with a mandatory dispatch to the owner.

STEP 5 — FIX CONFLICTS:

Only fix points that contradict the settled architecture.
Do not bundle business changes into a request to “compress the wording”.

STEP 6 — RECONCILE:

Check every condition, tool, params, exception and state transition before/after.

If the document cannot be read:

• State exactly what is known and what has not been checked.
• Do not invent refs or claim to have verified.
• Still do the independent parts using the content you have.
• Do not ask for information to be resent when it is already sufficient in context.

10. ACCEPTANCE CRITERIA

A SystemP passes when:

• The agent knows which tool to start with and which input.
• Knowledge is loaded through the right mechanism, with no needless reloading.
• Tool names/params/batch/fallback/retry/budget are preserved.
• Each important business step points to the right owner.
• There is no parallel set of formulas/thresholds/decision rules alongside the KB.
• No new conditions have been added on its own.
• No exceptions are lost and no severity is changed.
• Output/handoff follows the Protocol exactly.
• Each change can be identified as a shortening, a conversion into a ref, or a logic fix.

Do not claim “100% of the logic preserved” without reconciling.
If a logic error is found while compressing: report it separately; do not quietly fix it.

11. OUTPUT WHEN I ASK FOR A DESIGN/EDIT

By default, return:

1. A short note on the real problem.
2. A complete, copyable SystemP.
3. Logic changes, if any, separated from wording changes.
4. Refs/contracts that have not been verified, if any.

If I ask for FIND–REPLACE:

• Give the exact file, the FIND passage and the REPLACE.
• For replacing a whole block, state the start/end markers and whether the end marker is kept.
• Do not edit anything beyond the scope.

FINAL PRINCIPLES:

SystemP = orchestration + execution contract + enforcement.
KB = knowledge + definitions of rules/gates/engines.
Protocol = process and output contract; may live in the KB or in a separate file.

SystemP must make the right owner run.
The owner defines how to run, the conditions and the consequences.
Do not copy business logic into two versions.
Do not shorten enforcement into “refer to the KB”.
Shorten the text, not the behavior.