Prompt playbook

Anatomy of an engineering prompt

Agents fill gaps with plausible defaults. In engineering, plausible defaults are where errors hide: peak instead of RMS, g instead of m/s², Hz instead of orders. Close the gaps yourself with seven parts.

Part	What to write	Example
Role and goal	who it is for and what it does, in one sentence	"a page that flags pumps whose vibration has changed"
Context	asset, measurement, users, environment	"technicians on tablets, no network on site"
Input data	format, columns, units, sampling rate, size	"CSV: date, pump_id, velocity_rms_mm_s …"
Method	formulas, standards, thresholds, step by step	"residual > 3σ on 3 consecutive days"
Outputs	charts, tables, files, with units	"ranked table, worst first; CSV export"
Constraints	where it runs, what it must not do	"runs offline; no data leaves the computer"
Verification	a test case with a known answer	"6205 at 1,487 rpm → BPFO ≈ 88.8 Hz"

The last row matters most. A test with a known answer turns "looks right" into "is right", and it gives the agent a target it can check itself when it can run code.

Prompt builder

Pick a starting example, edit the fields, and copy the generated prompt into the AI tool you use.

Template library

Copy-ready prompts for recurring jobs. Replace the bracketed parts.

Ask for the plan before the code

Before you write any code, reply with:
1. The formulas you will use, with units for every quantity.
2. Every assumption you are making about the input data.
3. Anything in my request that is ambiguous, as questions.
4. How you will test the result against a known answer.
Wait for my confirmation, then build it.

Synthetic test data with ground truth

Write a generator for synthetic [vibration / motor current] test signals so I can verify my analysis tool.
- Sampling rate [25,600] Hz, duration [5] s, running speed [1,487] rpm.
- Cases: healthy; unbalance (strong 1×); misalignment (2× at 80% of 1×); outer-race defect with impacts at BPFO = [3.585] × running speed exciting a [4,200] Hz resonance.
- Add Gaussian noise with a parameter for signal-to-noise ratio.
- Save each case as a CSV with a time column, and print a table of the ground-truth frequencies and amplitudes for each case.

Clean a CMMS export

I have a CSV export of work orders with columns [wo_id, asset_tag, created, closed, type, description].
Write a Python script that:
- Normalises asset tags (trim, upper case, map the variants in the attached list to one tag).
- Parses dates in the formats [DD/MM/YYYY and YYYY-MM-DD].
- Flags likely duplicates: same asset, same type, created within 2 days.
- Classifies description text into [bearing, seal, coupling, electrical, lubrication, other] with keyword rules I can edit, and reports how many rows fell into "other".
- Writes a cleaned CSV and a summary of every change it made, so I can review them.

Anomaly detection baseline

Build a notebook that trains an anomaly detector on healthy feature data and evaluates it honestly.
- Input: CSV of features per window with columns [asset_id, timestamp, features..., label] where label is "healthy" or a fault name.
- Train Isolation Forest and a PCA reconstruction model on the first [60] days of healthy data per asset only.
- Set the threshold at the [99.5]th percentile of scores on a held-out healthy period.
- Report, per asset: alerts per month on healthy data, detection delay for each fault, and a plot of score over time with the threshold.
- Split by time, never by random shuffle, and say so in the notebook.

Report a bug precisely

Bug report.
Input: [demo signal "outer race", 1,487 rpm, 6205 bearing].
Expected: envelope spectrum peak at BPFO = 88.8 Hz with harmonics at 177.7 and 266.5 Hz.
Actual: the tool labels the peak at 177.7 Hz as BPFO and reports no peak at 88.8 Hz.
Please find the cause, explain it in one paragraph, fix it, and add a check that would have caught it.

Explain unfamiliar code

Explain this code to a mechanical engineer who does not program.
- Describe what each part does in plain language, in the order the data flows.
- List every formula with its units and the line where it appears.
- List every hard-coded number and what it means.
- Point out anything that could give a wrong answer without an error message.

Key takeaways

Write prompts like specifications: inputs, method, outputs, constraints, verification.
Always include a test case with a known answer.
Ask for the plan and assumptions before the code.
Report bugs with input, expected and actual values.