{
  "version": "act 2.8.1",
  "slug": "define-work",
  "name": "define-work",
  "description": "Turns a request into an approved design document before any code is written. Use when the operator asks to build, add, change or design something whose intent, scope or constraints are not yet settled (\"I want to add\u2026\", \"what should we build\", \"help me think this through\", \"let's design this\"), or asks to brainstorm, scope or spec a change.",
  "url": "https://act101.ai/docs/skills/define-work",
  "body_md": "# Define Work\n\nThis skill answers \"what should we build\". It ends with an approved design\ndocument. It does not plan and it does not build.\n\n## Adapt\n\nAn operator instruction, then the project's declared design workflow (its\ntemplate, location, review and approval steps), win over every default below.\nA workflow applies only when it is written down or the operator states it.\n\n## Procedure\n\n1. **Size the request** and tell the operator the size; they can change it.\n\n   | Size | Sign | Then |\n   |---|---|---|\n   | Clear task | Everything that matters is in the request. | Say so. Write the request as a one-line design document, which the request itself approves, and go to step 9. |\n   | Small change | The intent is clear; a few choices are open. | Steps 2\u20135, a short design document (step 6), then steps 8\u20139. |\n   | Project | Intent, scope or constraints are open, or several parts interact. | Steps 2\u20139, with a design document. |\n\n   When the work outgrows its size, say so and step up. A request that holds\n   several independent projects: agree an order and define one at a time.\n   The operator can skip the questions; that removes only step 3. State the\n   significant choices (platform, language, approach) in one line. Recon\n   (step 2), the alternatives (step 5), the document (step 6) and, for a\n   project, the verification stage (step 7) still run; step 7's questions\n   for the operator become author's calls, listed in the document. Then hold\n   at the approval gate (step 8).\n\n2. **Recon before questions.** Read the project instructions (CLAUDE.md,\n   AGENTS.md, CONTRIBUTING and the documents they name), the code and docs the\n   request touches, existing designs and specs, and any design or spec\n   workflow the project declares. Find what the repo contains where the\n   request lands, what the touched files declare, who uses the symbols the\n   change touches, and, for a structural change, what else breaks if they\n   change. Answer from the repo what the repo can answer; ask the operator\n   only the rest. A text match is not a binding: report each finding as what\n   it is.\n\n3. **Questions.** One question per message, in one sentence. Open questions\n   first, anchored in a concrete case (\"walk me through the last time this\n   went wrong\"); offer options only when the operator is stuck. When the\n   operator defers, propose a concrete default. Cover, as ground and not as a\n   script: purpose and what success looks like; goals; non-goals; what would\n   make it a failure even if it works; constraints; existing work and earlier\n   attempts; which implementation choices the operator wants to make and\n   which they leave to you. A choice you make goes in the design as the\n   author's call, never as the operator's.\n\n4. **Play back** each part as soon as you understand it, in a short\n   paragraph, with your guesses marked as guesses. The operator corrects it;\n   then go on to the next part.\n\n5. **Alternatives.** Weigh approaches privately and drop any that conflict\n   with the stated purpose. Show two or three, with your recommendation, only\n   when the choice is the operator's.\n\n6. **Design document.** Write it where the project keeps designs, else at\n   `docs/specs/YYYY-MM-DD-<topic>-design.md`. The project's template wins;\n   otherwise cover:\n   - intent: the problem, and why it matters now\n   - goals and non-goals\n   - constraints\n   - the decided parts of the approach, each marked as the operator's or the\n     author's call\n   - what is left to the builder\n   - acceptance: what \"done\" means, as checks a test or a command can decide\n\n   A small change's document is short: intent, the description, and\n   acceptance. Cite the recon evidence (file:line) for each claim about\n   existing code. Match the length to the substance; no filler sections.\n\n7. **Verification stage.** Give the document to a fresh reviewer that has\n   not seen this conversation, on a capable model, with this brief: you are\n   the builder who must plan from the document at `<path>` and cannot ask\n   its author; report only the questions where a wrong guess would change\n   the plan, each with why, most important first; skip what the document\n   leaves to the builder and what a builder could decide; if none remain,\n   say \"nothing important left\". Sort each question:\n   - answered by the conversation or the repo: write the answer in;\n   - minor: decide it, and mark it in the document as the author's call;\n   - the operator's: only the operator can answer it, and the answer changes\n     what gets built.\n\n   Send the operator's questions in one message, most important first, and\n   write the answers in. One round only.\n\n8. **Approval gate.** Nothing is built before the operator approves the\n   design document. Building is product code, scaffolding, dependency\n   installs or project creation; reading and recon are not. Hand over the\n   document with the list of author's calls, so the operator checks them\n   while reading; for a small change, show its text in chat and take the\n   approval there. Approval covers only the text the operator saw. An\n   explicit instruction to build without review (\"just build it\", \"no need\n   to approve\") is the approval. For every size, record it in the document\n   header: `**Status:** approved by <who> <YYYY-MM-DD>`. A spike the operator\n   agrees to is labeled throwaway; keeping any of it needs a new approval.\n\n9. **Hand over.** Give the operator the approved document's path. It is the\n   authority spec for planning. Planning follows the project's planning\n   workflow, or the operator's instruction.\n\n## Report\n\nThe design document is the report. Each claim about existing code cites its\nevidence. Each check that did not run is named in the document as not run,\nwith its reason."
}