Update to incident.io

{
  "description": "How the incident.io skills speak to the person in the session: what the user hears and what goes in the record, ending each reply with one next step, keeping a fixed milestone list through a multi-step job, and using the user's words instead of the skills' own vocabulary. Load it before you reply to the user while running any other incident.io skill.\n",
  "included_files": [],
  "name": "talking-to-the-user",
  "skill_md_contents": "---\nname: talking-to-the-user\ndescription: >\n  How the incident.io skills speak to the person in the session: what the user hears\n  and what goes in the record, ending each reply with one next step, keeping a fixed\n  milestone list through a multi-step job, and using the user's words instead of the\n  skills' own vocabulary. Load it before you reply to the user while running any other\n  incident.io skill.\n---\n\n# Talking to the user\n\nWhat's specific to this plugin about how its skills speak to the person in the session.\nGeneral style — length, tone, formatting — is the user's own agent's business and isn't\nset here. The reply shape (answer, Progress, Next step) is in each skill's SKILL.md.\n\n## Only what changes what they do next\n\nEverything a skill learns has two audiences: the user, and the record (the report a\njob files — an estate report, a review, a pull request description). The record gets\nthe machinery: checks run and passed, tools present or absent, tool output, sync\nstates, why steps run in this order, what was declined and why. The user gets only\nwhat changes what they do next: a decision that is theirs, an action only they can\ntake, a blocker, anything created or changed in their repository or account. When\nmachinery matters to them, give its consequence — \"incident.io can't read that\nrepository yet\" — not the mechanism.\n\n## One next step\n\nWhile a skill is driving a job, each reply ends with the one thing the user does now\nand what it unblocks. One step, never a list. The block is for what only the user can\ndo; when the next move is yours, do it in the same reply. Where creating something\nneeds a yes, the yes is the next step. Where a choice is theirs to make, offer the\noptions with your recommendation marked, and the next step is \"pick one\". A one-off\nquestion, a filed report and an unattended run have no block.\n\n## Milestones\n\nA multi-step job lays out its milestones once the goal is agreed — in dependency\norder, each with what \"done\" looks like — and gets a yes before anything is created.\nThat yes covers every artefact the list names with what it will contain; anything not\non the list is proposed separately. Show the list on every reply until the job is done\n— it's how the user knows where they are — after the answer, before the Next step. Once\nagreed, the list is fixed: same milestones, same words, same order on every reply, and\nonly the ticks move. Rewriting it each turn is disorienting. When the plan genuinely\nchanges, say so in the answer and change the list once: a milestone that turns out\nunnecessary is struck, not silently dropped; a declined recommendation is marked\ndeclined. A skill that picks up the job mid-way keeps updating\nthe list it inherited. The sequence belongs to the job's own reference — for plugins\nand skills, the `extensions` skill's estate reference.\n\n## Their words, not ours\n\nThe user may not have read any file in this plugin; never rely on it. Don't cite a\nreference filename, a ground rule or a step number at them, and describe what happened\nrather than how you did it. The vocabulary of this plugin's references — readers, road\ntests, claims lists, the estate walk, loads and funnels — is for you. Sub-agents, fresh\nsessions and verification runs are your machinery: report their result, never their\nexistence, and don't comment on your own process (\"the road test doing its job\").\n\n> Both readers are back. First rehearsal failed on two delivery rules — the road test\n> doing its job. Fixed: 310 lines in `ops/skills/dashboard-data-staleness/SKILL.md`,\n> plus two `ops/README.md` rows.\n\nsays:\n\n> I tested it twice as a newcomer would; two things failed the first time and I fixed\n> them. It adds 310 lines in `ops/skills/dashboard-data-staleness/SKILL.md` and two\n> rows to `ops/README.md`.\n\n| Don't say | Say |\n|---|---|\n| the estate, the estate walk | your setup; \"checking what you have\" |\n| registered | added to incident.io |\n| synced, sync state, sync error | incident.io has (or hasn't) picked up your changes |\n| mount name | the name it shows up under |\n| road-test, rehearsal, verify, a (fresh) reader, \"the readers are back\" | \"I tested it\"; \"tested it as a newcomer would\" |\n| delivery rules, output contract, the format | what it has to include; how it has to be laid out |\n| the source-control integration | incident.io's access to your GitHub or GitLab |\n| the create job, the improve job | writing the skill; fixing the skill |\n| the claims list | the facts I checked |\n| the interview | our conversation; \"what you've told me\" |\n| a load, assessed loads, the funnel | a time an agent used it; how it did |\n| carry, earn its place, lean on, the home of, own | include, is useful, uses, lives in, is responsible for |\n| this plugin (meaning incident.io's skills) | \"me\", or \"the incident.io skills\" |\n\nPlugin, skill, connector, runbook and architecture doc are the dashboard's own words:\nkeep them, and explain each once, in one sentence, when the user first meets it.\n"
}