# Guide refinement — 2026-10-23

The current guides follow the [AI Agent Manifesto](https://tinyhat.ai/chore/manifesto).

Design judgement: optimize the next useful provider response per unit of homeowner effort. This is an authoring standard, not an exhaustive checklist prescribed by Farid. The explicit role boundary is that the user's agent prepares the job context; providers supply quotes and availability. The two-section guide format and plain Markdown contract remain unchanged.

Applied the [authoring meta-skill](/meta-skill.md) to the 14 current service guides. All now state the provider/user role distinction and that budget is not a mandatory standard field. Five guides gained short synthetic examples where a concrete next action improves on an abstract instruction. Other working service-specific content and source dates were retained.

| Synthetic case | Before: actual guide weakness | Revision and expected next step |
| --- | --- | --- |
| Furnace replacement: Winnipeg, gas and still heating already supplied; model/budget unknown | “Do not repeat answered questions” was correct but left the first useful action abstract. | Carry those three facts forward; compare replacement assessments and ask installers for sizing, itemized options and availability. Do not ask the user for a provider quote or require model/budget first. |
| Snow: Calgary driveway/public sidewalk known; maps declined | The guide accepted refused measurements but had no concrete combined example. | Propose current/coming season standard plans for correction, research return/ice terms against the sidewalk duty, leave dimensions for assessment. Ask only about an access deadline if consequential. |
| Recurring cleaning: Vancouver, biweekly already chosen, floor area unknown | The general biweekly default could distract from already chosen context. | Keep that cadence, compare scope and first-clean assessment, ask providers for estimates and availability. No floor-measurement or budget gate. |
| Drain: one slow kitchen sink, assessment inquiry authorized | “Propose a diagnostic assessment” did not explicitly distinguish provider pricing from user intake. | Research service fit and fees; leave dimensions/cause unknown. Do not demand a user-supplied plumber quote or a risky intake test. |
| General fallback: gutter cleaning in an unresearched neighbourhood, no measurements | “Start from what the person wants” was useful but abstract for missing specialist coverage. | Research genuine gutter-service fit and seek an assessment-based quote; do not expose routing failure, invent height or ask the user to climb. |

These are **author walkthroughs and instruction changes**, not receipts of fresh model/ChatGPT behaviour, provider acceptance or booking. Existing browser observations belong to the separate QA owner. Local contract tests verify structure and API/MCP/page parity; they do not establish that a model consistently follows the improved examples. Follow-up critique should use actual observed outcomes rather than expand this into a framework.