Prompt authoring guide

1. Foundational mindset

Platform Agent ≠ vanilla ChatGPT

combo agents wield tools actively—retrieve KB chunks, paginate PDFs, author files, edit Office binaries—and ship with a Skill marketplace so domain procedures stay standardized.

Dimension	Plain chat	combo-agent prompting
Knowledge	Memorized weights only	KB + uploads + historical artefacts
Task shape	Single turn typical	Multi-step pipelines
Artefacts	Chat text only	DOCX/XLSX/MD binaries
Depth	Generalist	Skill-augmented experts
Quality gates	Manual review only	Automated checks + ES verification loops

Longer ≠ better

Ten techniques appear below—many jobs never need them all. Agents plan reasonably well; terse instructions often suffice.

Minimal examples that usually work:

Compare the two documents titled "Requirements analysis validation" inside this KB—focus on drive-mode deltas.

/document-editing /docx
Add deterministic IDs to each child requirement inside the uploaded EEA document formatted as GAC_<feature>_<counter>.

Tighten prompts only when you observe repeatable misses (skipped documents, sloppy numbering, missing citations, unstable progress tracking).

Principle: start concise, iterate surgically—this chapter is your toolbox, not mandatory boilerplate each time.

2. Skill system primer

What is a Skill?

A Skill packages professional workflows (SKILL.md + tooling). Prefix messages with /skill-name so the orchestrator adopts that playbook.

Frequently used Skills

Skill	Invocation	Purpose
document-editing	`/document-editing`	KB-aware partial edits
docx	`/docx`	Author/edit Word binaries
patent-agent	`/patent-agent`	Draft filings from disclosures
patent-doc-formatter	`/patent-doc-formatter`	Patent-office formatting

Combining Skills

/document-editing /docx
Task: enumerate numbering rules for nested requirements inside EEA_DOC_…

Typical pairing:

Skill	Responsibility
document-editing	KB search → pinpoint blocks → snapshot updates
docx	Low-level XML/word processing

When to activate Skills

Task	Need Skill?
Read-only analysis/reporting	Optional—`search` + `execute_code` may suffice
Patch KB-hosted Office files	Yes `/document-editing` + `/docx`
Create brand-new Word deliverables	`/docx`
Patent workflows	`/patent-agent` / `/patent-doc-formatter`

3. Ten core techniques — read me first

Not every bullet below belongs in every ticket. Severity codes:

Tag	Meaning	When it matters
🔴 Mandatory	Skipping commonly breaks correctness	Precision rules, binary edits, chained tasks
🟡 Recommended	Big quality lift for heavy programs	Huge doc sets, audits, production prompts
🟢 Optional	Nice-to-have polish	Exploratory one-offs, compact corpora

Heuristics:

Two or three modest documents — a crisp paragraph plus KB naming is typically enough for the planner.
10+ artefacts or 50+ page tomes — layer in phasing, indices, checkpoints.
Numbering / formatting / hyperlinks — spell mechanics explicitly or the Agent improvises.

Technique 1 — Summaries as indices, then drill down 🟡

Detail calibration: skip the index for two or three short documents. Build it when you have five or more sources or any single artefact beyond ~50 pages.

Pain: dozens of 50+ page PDFs cannot fit one context window; “compare everything” collapses.

Flow:

Paginate each source, emit a table of “entry name / module / chunk_ids”.
Later, call list_chunks(chunk_ids=..., window=…) for targeted diffs.

Snippet:

Scan every document sequentially.
After each file finishes, emit a markdown table:
| doc | module | entry | chunk_ids | dimensions |
Never advance to the next doc until the current one is fully read.
chunk_ids are mandatory for reruns.

Comparison pass:

For each paired entry, reuse recorded chunk_ids via list_chunks(window=5).
Cite doc + chunk_id excerpts for every statement—no memory-only summaries.

Benefit: reproducible, auditor-friendly diffs instead of lossy paraphrases.

Technique 2 — Phased execution + checkpoints 🟡

Pain: long jobs die mid-flight—work is lost without intermediate artefacts.

Flow: name explicit phases, write_file after each milestone, read_file before the next.

Snippet:

⚠️ Persist each phase before moving on.
Phase 1 methodology → methodology.md
Phase 2 per-doc indices → index.md
Phase 3 pairwise diffs → outputs/diff_<pair>.md
Final → execute_code + XLSX workbook

Maintain a TODO table with ✅/⏳ and “Completed M/N cohorts” breadcrumbs.

Technique 3 — Lateral extraction across N docs 🟡

Pain: heterogeneous structures hide the “same” capability across sources.

Steps:

Pick the richest document as anchor.
For every anchor row, search/list_chunks sibling corpora.
Reverse scan for rows missing on the anchor → mark “new/supplement”.

Technique 4 — Discover taxonomies from data 🟢

Pain: automotive specs mix platform, E/E generation, powertrain, etc. Blind assumptions miss dimensions.

Directive: “List every classification axis you actually observe—do not hallucinate axes.” Provide examples as non-binding hints, then enforce comparisons only within identical axis values.

Always compare within identical dimension buckets; never mix BEV vs ICE signal sets, for example.

Technique 5 — Mandatory citations 🟡

Pain: models paraphrase without evidence.

Requirement: every factual claim lists document + chunk_id + verbatim snippet. If data missing, say so explicitly.

Benefits: auditability + reduced hallucination load.

Technique 6 — Control comparison grain 🟡

Pain: default answers stay at feature level; engineering needs signal/config parity.

Compare at least:
 - signal names, directions,Tx types, parsing rules
 - calibration codes, defaults, factory resets
 - enumerated option ordering
 - transition/trigger logic
 - numeric thresholds
Also label each delta: identical / elaborated / reduced / missing / conflict / net-new.

Technique 7 — Binary edit loop (🔴)

Flow (document-editing/docx):

1. copy_kb_document → workspace
2. unified_search ES to locate targets
3. execute_code mutate docx → write_file_bytes
4. snapshot_and_index (⚠️ mandatory for re-searchability)
5. Re-query new ws_doc_id to verify

ES-first retrieval

Need	Correct	Wrong
Find requirement text inside docx	`search(query=..., doc_ids=...)`	`read_file` whole binary
Diff two corpora	Scoped searches per artefact	Streaming entire files

snapshot_and_index hygiene

Each revision pass must re-index; multi-step edits (“numbering → hyperlinks → styles”) each need their own snapshot.

Technique 8 — Chained tasks with explicit IO (🔴)

Document Task A outputs become Task B inputs.

Task A numbering
  Input: EEA3.0_…docx
  Output: *_numbered.docx

Task B cross-links — prerequisite: NEVER re-number; only embed hyperlinks referencing Task A artefacts.
Inputs: GAC SRS + *_numbered.docx
Outputs: *_linked.docx + mapping.xlsx

Suffix conventions (_numbered, _linked) keep lineage obvious.

Technique 9 — Mechanical rules spelled out (🔴)

For numbering/mapping/normalization enumerate format • scope • exclusions • counters • exemplar before/after.

Without that structure the model improvises—in bulk edits improvisation is catastrophic.

Technique 10 — Post-edit ES verification 🟡

After automation, sample search anchors:

search(query="GAC_ExtLightSys_01", doc_ids="<new>")
Expect chunk describing fog-lamp indication requirement.
Confirm hyperlinks hop bidirectionally when files sit in same folder.

Deterministic asserts miss semantic linkage errors—Elasticsearch spot checks mimic human acceptance tests.

4. Prompt structure templates

Template A — Analysis / comparison (read docs → deliver a report)

Role
  You are a [domain] [role].

Task
  Using [method / standard] from KB «XXX», analyze [target documents] inside KB «YYY».

Core principles
  1. [Analysis constraints, e.g., “compare within the same dimension bucket only”]
  2. [Citation rules, e.g., “every conclusion lists a source”]
  3. [Quality bar, e.g., “minimum granularity down to parameters / signals”]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 1 — [Name] (estimated rounds)
  Steps:
    1. [Concrete action, including tooling]
    2. [Concrete action]
  Output artefact: [filename]
  ⚠️ Persist with write_file when done

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 2 — [Name] (estimated rounds)
  ⚠️ read_file the Phase 1 artefact before starting
  Steps:
    1. [Concrete action]
  Output artefact: [filename]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase N — Executive report
  Generate the final workbook via execute_code (Excel / Word)
  Report structure: [sheet / chapter outline]
  Acceptance checks: [explicit criteria]

Template B — Document editing (mutate KB-hosted files)

/document-editing /docx

Task 1 — [Operation name]

[Rules]
- Format: [exact pattern]
- Scope: [what to touch]
- Exclude: [what never to touch]
- Counting / matching logic: [explicit rules]

Example
  Before: [...]
  After:  [...]

Paths
- Input:  [source.docx]
- Output: [source_<suffix>.docx]

Validation
  [How you will prove correctness]

---

Task 2 — [Operation name]

Prerequisite: consume Task 1 output [_<suffix>.docx] only—do not repeat Task 1.

Hard constraints
- [Operations that would corrupt upstream work]

[Rules]
- [Additional rules]

Paths
- Inputs:
  - [fileA.docx]
  - [Task1 output.docx]
- Outputs:
  - [fileA_<suffix>.docx]
  - [fileB_<suffix>.docx]
  - [mapping_table.xlsx]

Validation
  [How you will prove correctness]

5. Common anti-patterns (prompt pitfalls)

Anti-pattern 0 — Editing documents without activating Skills

❌ "Please edit chapter 3 of this Word doc in the KB."

Without /document-editing, the Agent may read_file the binary (garbage), or rebuild the file from scratch (format loss).

✅ /document-editing /docx
Adjust chapter-3 heading styles for the EEA document in the KB …

Anti-pattern 1 — One-line vagueness

❌ "Compare the differences across these documents."

The model samples random paragraphs—coverage is undefined.

✅ Follow the phased structure in this playbook: inventory → targeted pulls → matrixed diffs.

Anti-pattern 2 — Missing KB scope

❌ "Search anything about drive modes."

Wide retrieval across every KB dilutes signal.

✅ "Inside KB «Requirements analysis validation», search for drive-mode related requirements."
   or: search(query="drive mode configuration flow", kb_ids="Requirements analysis validation")

Anti-pattern 3 — No intermediate checkpoints

❌ "Analyze all ten documents, then give me the final report."

Any mid-run failure invalidates the downstream narrative.

✅ After each doc (or comparison cohort), write_file a checkpoint before continuing.

Anti-pattern 4 — Memory-only diffing

❌ "Summarize the differences from what you read earlier."

Context compaction may erase the earlier chunks entirely.

✅ For every diff statement, re-fetch list_chunks(chunk_ids=...)—never rely on conversational memory.

Anti-pattern 5 — Unbounded comparison grain

❌ "How do the two documents differ?"

You only get feature-level platitudes.

✅ Enumerate dimensions: signal defs, calibrations, defaults, trigger logic, thresholds, etc.

Anti-pattern 6 — Fragmented keyword search

❌ search(query="light fault alarm position lamp")

Token splitting harms embedding quality.

✅ search(query="Lighting fault diagnostics covering position and turn indicators")
   Full-sentence queries embed best.

6. Image / UI comparison add-ons

Use these when the job is screenshot or HMI parity review.

6.1 Build an image index before diffing

For every doc_id across the two KBs, call list_chunks and collect chunks that contain image_url.
Tag each image with its functional module.
Pair images that represent the same capability across KB A and KB B.
List any orphan images that cannot be paired.

6.2 Descriptions must flow from describe_image

⚠️ Every UI description must come from an actual describe_image call—no improvisation.
⚠️ Never skip describe_image and jump straight to conclusions.

6.3 Structured comparison checklist

Analyze the screenshots along these axes:
  1. Layout (element placement, hierarchy, column structure)
  2. Controls (toggles, sliders, tabs, dialogs—types and states)
  3. Information density (functions per screen)
  4. Visual language (palette, corner radii, spacing, type scale)
  5. Capability gaps (only in A / only in B / same idea, different implementation)

7. Platform tool quick reference

Useful primitives you can name directly inside prompts.

Retrieval (reading content)

Action	Tool call	When to use
List KB documents	`list_documents(kb_ids="Knowledge base name")`	Discovery
Read a document end-to-end	`list_chunks(doc_ids="Document ID")`	Paginated deep read / index build
Fetch specific chunks	`list_chunks(chunk_ids="id1,id2")`	After you already know chunk IDs
Expand local context	`list_chunks(chunk_ids="id", window=5)`	Pull neighbours around a hit
Semantic search	`search(query="Natural language…", kb_ids / doc_ids=…)`	Fuzzy location
Vision	`describe_image(image_url=…)`	UI / plot screenshots

Files (authoring / editing)

Action	Tool call	When to use
Save intermediate notes	`write_file → outputs/name.md`	Checkpoints
Generate binary reports	`execute_code` (Python + openpyxl, etc.)	XLSX/DOCX outputs
Hydrate workspace copies	`copy_kb_document(doc_id)`	Before surgical edits
Refresh ES after edits	`snapshot_and_index(parent_ws_doc_id, output_path)`	⚠️ Mandatory for re-search

Skill triggers

Scenario	Invocation
Edit KB-hosted Office files	`/document-editing`
Low-level Word operations / new docs	`/docx`
Patent drafting	`/patent-agent`
Patent-office export	`/patent-doc-formatter`

8. Full worked examples

Example A — Multi-document requirements gap analysis (analytical)

Role
  You are an automotive HMI requirements analyst.

Task
  Compare multiple requirement documents inside KB «XXX» and deliver a structured variance workbook.

Core principles
  1. Compare only within identical dimension buckets—never mix platforms or powertrains.
  2. Discover classification axes from the corpus—do not invent axes up front.
  3. Each statement cites document name + chunk_id + verbatim excerpt.
  4. Final deliverable is an XLSX report.

⚠️ After every phase, write_file before advancing.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 1 — Full pass + taxonomy discovery (≈3–5 rounds)

  Goal: Finish every document, enumerate real dimensions, mint a traceable index.

  Steps:
  1. list_documents → inventory
  2. For each document, paginate with list_chunks until EOF
  3. Extract doc type, functional module, taxonomy axes, entry→chunk_id map

  Artefacts:
  - document_manifest.md
  - taxonomy_axes.md
  - comparison_group_matrix.md
  - requirements_index.md (entry → chunk_ids)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 2 — Pairwise / cohort deep dives (many rounds)

  ⚠️ read_file all Phase 1 artefacts first

  For each cohort in comparison_group_matrix:
  1. Choose the baseline document
  2. Pull chunk_ids via list_chunks
  3. search/list_chunks in sibling docs to locate counterparts
  4. Fill in the matrix with variance labels + citations
  5. Reverse-scan for entries missing from the baseline → mark as “net new / suggest add”

  write_file after each cohort; end every round with “Completed M/N cohorts”.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 3 — Consolidation (≈1 round)

  execute_code + openpyxl → XLSX
  - Sheet 1: Exec summary (doc list, axes, KPIs)
  - Sheets 2-N: One sheet per cohort
  - Final sheets: missing-items list + citation appendix

Example B — Numbering + mutual hyperlinks (document editing)

/document-editing /docx

Task 1 — Number child requirements

Assign unique IDs to every qualifying child requirement inside the EEA document.

Numbering rules
- Pattern: GAC_{L1 capability name}_{counter}
- Only X.X-level child headings (e.g., 3.1, 3.2); never X.X.X
- Skip table of contents, level-1 headings, narrative paragraphs
- Each L1 capability resets its own 01… counter
- Append the ID at the end of the in-body heading text—leave the TOC untouched

Example
  Before: 3.1. Fog-lamp tell-tale
  After:  3.1. Fog-lamp tell-tale (GAC_Exterior lighting & IDC interaction_01)

Paths
- Input:  EEA3.0_Cluster_V3.4.docx
- Output: EEA3.0_Cluster_V3.4_numbered.docx

---

Task 2 — Cross-link SRS ↔ EEA

Prerequisite: reuse Task 1’s *_numbered.docx—do not re-run numbering.

Hard constraints
- Insert hyperlinks only—do not mutate IDs or body copy

Mapping rules
- 1:1 perfect match
- 1:many external→internal
- many:1 internals→external

Paths
- Inputs:
  - GAC_System_Requirements_V6.5.docx
  - EEA3.0_Cluster_V3.4_numbered.docx
- Outputs:
  - GAC_System_Requirements_V6.5_linked.docx
  - EEA3.0_Cluster_V3.4_linked.docx
  - requirements_mapping.xlsx

Validation
  1. From GAC FUNC_XXXX hyperlinks → land on the correct EEA row
  2. From EEA GAC_ID hyperlinks → land on the correct GAC row
  3. With both files in one folder, relative links still resolve

9. Iterating on prompts

Preferred cadence: start small, add constraints only where the last run failed.

Round 1 — Minimal prompt
  → Observe how the Agent interpreted the mission

Round 2 — Targeted guardrails
  → Skipped docs? Add “read every file fully, no skipping.”
  → Shallow diffs? Add explicit dimension lists.
  → Wrong numbering? Add worked before/after exemplars.

Round 3 — Template-ize
  → Once stable, snapshot the prompt as a reusable playbook.

Concrete tightening tactics:

Lead with ⚠️ where failure is common—models weight those lines strongly.
Show positive + negative phrasing — e.g., “Don’t write ‘styles look similar’ ❌; instead ‘A uses rounded cards vs B uses squared lists’ ✅.”
Cap batch size — e.g., Process at most five requirements per iteration when quality drops at scale.
Use heavy separators (━━━, ═══) between phases so boundaries stay obvious.
Avoid constraint dumps — fix one or two failure modes per iteration; over-constraining causes new omissions.

Prompt authoring guide

On this page