# Capturing the procedure, conventions and failure modes Read this at step 3. The goal is a filled [../assets/capture-worksheet.md](../assets/capture-worksheet.md) built from evidence first and questions second. A skill written from an interview alone encodes how people think the job works; a skill written from real runs encodes how it actually works, including the corrections. Contents: - Sources, in priority order - What to extract from each run - Question bank - Failure mode record - Gotchas worth recording - Turning answers into rules, tests and context diffs ## Sources, in priority order 1. 3 to 5 recent real runs, redacted as described below, each with its inputs, the delivered output, the corrections the reviewer made and how they checked it. Ask for the redacted copies when you ask for the runs. 2. Reviewer comments on those runs (tickets, document comments, chat threads). 3. Incident notes where the job went wrong in production. 4. SOPs, runbooks and checklists. Treat them as claims to verify against the runs; they drift. 5. Chat threads where someone explained the job to a colleague. 6. Existing prompts or command files the team already uses. Redact before anything is copied into the drafts folder: replace names, emails, account and record IDs with placeholders. Keep the column layout, value formats and edge cases; drop the personal data. ## What to extract from each run - Inputs: file or report name, filters, date basis (event, click or report date), time zone, the complete-data cutoff, and where each input came from. - Steps actually taken, in order. - Each decision and the rule behind it ("excluded day 10 because the export flagged it incomplete"). - Corrections and why the reviewer made them. - Output format and where it went. - The reviewer's checks: what they looked at and what made them accept it. Put each item in the worksheet field it belongs to. When two runs disagree, record both and ask the owner which one is the rule. ## Question bank Ask in rounds, at most seven questions per message, each naming the worksheet field it fills. Skip anything the runs already answer. "Don't know" becomes an open item with an owner and a date. Round 1, decision and consumer: - Which decision does this output support, and who makes it? (job_and_decision) - Who reads the output and in which tool? (consumer) - What happens if the output is late or wrong? (must_not) Round 2, inputs and routes: - Which exports or reports does the job read, with which filters? (inputs) - How can those be read without write access? (read_only_route) - For an MCP read, which server and tool, by the names configured in `stack.md`, and which export stands in when that tool is missing? (read_only_route) - What is the date basis and time zone of each? When is a day complete? (inputs) Round 3, definitions and owners: - Which metric definitions does the job use, and where do they live? (martech_context_refs) - Who owns each definition? Is it in `metrics.md` with a version? (martech_context_refs) Round 4, thresholds: - At what value do you act? Give the number and unit. (thresholds) - From when does the rule apply (day of month, minimum sample, data maturity)? (thresholds) - What is excluded (test campaigns, internal traffic, brand terms)? (thresholds) Round 5, must-not conditions: - What must the output never do or claim? (must_not) - Which systems must never be changed by this job? (must_not) Round 6, edge cases (each becomes an output case): - What happens with a missing input, conflicting sources, zero rows, a partial day, duplicates, an unknown value, or odd text inside the data? (edge_cases) Round 7, acceptance and hand-off: - How do you check the output today, and how long does it take? (acceptance_checks) - Who acts on each part of the output, in which tool? (hand_offs) - Who approves changes to the procedure? (owner) ## Failure mode record Write every incident and every recurring correction as four fields: - Symptom: what someone saw. - Cause: why it happened. - Detection: the check or test that catches it, ideally before release. - Prevention: the rule, template field or enforcement that stops it. Example, pacing review: - Symptom: Monday's pacing report flagged Meta as 31% under budget; by Tuesday it was on pace. - Cause: the export included the current day, which was loaded only up to the morning. - Detection: the cutoff is the latest date in the file, or that date's rows are flagged incomplete. - Prevention: rule "use only days with data_complete true; name the cutoff in the summary"; boundary output case with a partial day. ## Gotchas worth recording Facts that defy a reasonable assumption belong in the skill body, with a checked date. Examples to verify live before copying: - Money units differ by API: Google Ads amounts are in micros and Meta budgets are in the currency's minor unit (cents for USD), per agent-write-safety's checks. A budget read straight from an API can be off by a factor of 100 or 1,000,000. - A CRM "last activity date" usually records logged sales activity (calls, emails, meetings), not product use. Check the property definition before using it as an engagement signal. - Changing a GA4 property's reporting time zone applies to data going forward; earlier days are not reprocessed. Comparisons across the change date need a note. - A platform UI total and an export total can use different attribution or date settings; record which one the reviewer trusts. ## Turning answers into rules, tests and context diffs - A decision with a threshold becomes a rule in the procedure, written with the number and the condition. - A correction that happened more than once becomes a rule plus an output case that would have caught it. - An edge case becomes one of the six output case kinds in [testing.md](testing.md). - A definition (metric, field meaning, naming rule, owner) becomes a proposed diff to `martech-context/` through marketing-context-kit. The skill then cites the path and the versioned ID, for example `martech-context/metrics.md` `pacing_rule_v1`, and never restates the formula. - A must-not condition becomes a boundary line and, where a tool could break it, a permission rule plus a permission test. - An unanswered question stays an open item in the worksheet; the skill does not ship with a guessed rule.