# Shaping Work > Shape rough ideas into clear, actionable work definitions. Use this skill whenever someone has an unstructured idea that needs to become a concrete work definition — feature requests, bug reports, PRDs, customer feedback, Slack threads, stakeholder asks, or vague "we should do X" statements. Trigger phrases include "shape this", "scope this", "write a PRD", "define this work", "turn this into a ticket", "flesh this out", "spec this out", "what should we build for X", "I have an idea for...", or any rough input that needs structure before implementation can begin. - Skill: `teambrilliant/shaping-work` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add teambrilliant/shaping-work` - Raw SKILL.md: https://api.skillmd.com/api/skills/teambrilliant/shaping-work/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: teambrilliant (https://skillmd.com/u/teambrilliant) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/teambrilliant/shaping-work --- # Shaping Work Shape ambiguous ideas into clear work definitions. Focus on clarity, not process theater. ## Principles - **No jargon** — write so anyone can understand - **Product-focused** — define *what*, not *how* to build it - **Right level of detail** — enough to act on, not a specification - **Flag unknowns with recommendations** — surface risks early, but always propose a resolution ## Process 1. **Understand the request** — Read the input (could be anything: a Slack thread, a rough idea, a customer complaint, a formal PRD, or a handoff from product-thinker). If intent is unclear, ask up to 3 targeted questions, then shape with stated assumptions. 2. **Understand the context** — If handed off from product-thinker, use the product context and analysis already gathered (don't re-explore). Otherwise, if working in a codebase, read `.tap/product.md` if it exists (current focus, bets, non-goals — what this work has to ladder up to), then CLAUDE.md or similar to understand what the application does (the product, not technical details). 3. **Shape the work** — Write the definition using the output format below. Pick the template variant that fits the type of work. 4. **Surface unknowns with recommendations** — For every unknown, propose a recommended resolution and list discarded alternatives with reasoning. Never ask "what do you want?" — propose what you'd do and why. 5. **Save the document** — Save to `thoughts/research/YYYY-MM-DD-descriptive-name.md`. ## Output Format **Always open with a Shaped View block** — a compact ASCII overview of what was shaped. This signals shaping was applied and gives an instant high-level picture without scrolling through the full document: ``` `★ Shaped View ───────────────────────────────────` [problem] → [solution] ├─ [key flow or behavior 1] ├─ [key flow or behavior 2] └─ [key constraint or open question] `─────────────────────────────────────────────────` ``` Rules for the block: - Appears **first**, before the full shaped document - One `[problem] → [solution]` line, then 2-4 tree branches max - The entire block should fit in one screen — if you need to scroll, it's too long - Use ASCII tree characters (`├─`, `└─`) for structure Then continue with the full shaped document below. The core structure adapts to the type of work. Always include: title, description, acceptance criteria, rollout & rollback, and risks/unknowns. Features and improvements also carry strategic fit; bug fixes don't (a broken thing gets fixed regardless of which bet it sits under). The middle sections flex based on what you're shaping. **Rollout & rollback rules** — every shaped feature/improvement gets a one-line answer to "how does this ship and to whom?" Walk the decision tree in [implementation-planning/references/rollout-primitives.md](../implementation-planning/references/rollout-primitives.md): 1. **Contract test:** is a shared contract changing? (schema, public API, multi-consumer interface) → plan expand-contract. 2. **Launch-strategy test:** who should see this, and when? Cohort, tier, geo, timing, %-rollout, A/B, dogfooding → flag (launch flag). 3. **Kill-switch test:** if this went bad in prod, what would I do? Flip a flag in seconds → flag (risk flag). Revert + redeploy is fine → no risk flag. Flags serve two purposes — *launch control* (who/when) and *reversibility* (turn-off). Either justifies a flag. A safe feature with a coordinated launch still gets a flag, for the launch. Default is **no flag, no expand-contract** — pick the lightest mechanism(s) that produce the launch control AND reversibility actually needed. Bug fixes never get flags. One flag per feature, never one per phase. Don't stack ceremonies. **Dev harness rules** — alongside "how does this ship?", every shaped feature answers: **"how does an implementer iterate on this without walking the full user flow?"** Read [implementation-planning/references/dev-harness.md](../implementation-planning/references/dev-harness.md) and name: 1. The fastest loop the riskiest part can run in — fixture-fed function, direct trigger, seeded UI. If the honest answer is "only the full flow", reshape until it isn't. 2. The shape-level requirements that buy that loop: raw inputs persisted at the boundary (replayable), secondary entry points (no one-time funnel as the only door), which real-world inputs get captured as fixtures — and, when outputs are judged rather than diffed (or their product UI ships later), that an out-of-app inspection surface is required. These are requirements, not implementation details — "the raw upload is stored and reprocessable" belongs in a shape; the script that does it belongs in the plan. Scale it: LLM cores, parsers of messy input, and integrations get the full treatment; a CRUD screen might need one line ("trivial — direct route + seeded data"). **Strategic fit rules** — every shaped feature/improvement names the bet it serves, in one line. Read `.tap/product.md`: 1. **Serves a bet** → name it and say how. One line, not a pitch. 2. **Serves no current bet** → say that explicitly, with why it's worth doing anyway (table stakes, support cost, unblocks a bet). A legitimate answer — but a stated one. 3. **Contradicts a non-goal** → stop and surface it before shaping further. A non-goal is a decision already made; reversing it is the user's call, not a detail to shape around. 4. **No `.tap/product.md`** → write "no durable product context in repo" and shape anyway. Don't block. Mention `/tap-skills:curate-product-context` once, in the handoff, not in the document. The point is traceability: work whose connection upward can't be stated is work nobody can prioritize against anything. **Acceptance criteria rules** — this section is the contract consumed downstream by planning and QA: - Each criterion must be **independently testable** in a browser or database — someone can verify it pass/fail without reading the code. - Describe observable behavior, not implementation ("badge shows `99+` for 100+ items" — not "use `Math.min(count, 99)`"). - No vague criteria ("works well", "is fast", "handles edge cases"). If a criterion can't be checked, it doesn't belong here. - Prefer specifics over generalities: concrete inputs, concrete states, concrete outputs. ### Feature work ```markdown ## [Clear, descriptive title] [1-2 sentence description of what this feature does, who it's for, and why it matters] ### Strategic Fit [One line: "Serves bet: [name] — [how]" | "No current bet — [why it's worth doing anyway]" | "No durable product context in repo"] ### Acceptance Criteria - [Observable behavior, not implementation detail] - [What triggers this feature/flow] - [What the user sees or experiences] - [Key states and edge cases] ### Designs [Link to Figma/designs if provided, or "N/A"] ### Rollout & Rollback [One of: "neither — direct deploy" | "expand-contract on [schema/API/interface]" | "flag at [user-visible boundary]" | "both — expand-contract on [surface] + flag at [boundary]"] [One-line reasoning. Reference [implementation-planning/references/rollout-primitives.md](../implementation-planning/references/rollout-primitives.md) decision tree.] ### Dev Harness [Fastest loop for the riskiest logic + the shape-level requirements that enable it: replayable inputs? fixtures from real data? entry point that skips the funnel? 1–3 lines; "trivial — direct route + seeded data" is a valid answer. See [implementation-planning/references/dev-harness.md](../implementation-planning/references/dev-harness.md).] ### Risks & Unknowns - **[Question or risk]** Recommend: [option] — [why] Discarded: [option] ([why not]) ``` ### Bug fix ```markdown ## Fix: [what's broken] [1-2 sentence description of the bug and its user impact] **Current behavior**: [what happens now] **Expected behavior**: [what should happen] **Reproduction**: [steps or conditions to trigger] ### Acceptance Criteria - [The specific broken behavior that should be fixed] - [Any related edge cases to verify] ### Rollout & Rollback Direct deploy — bug fixes ship to everyone. Rollback: revert if it introduces a regression. ### Risks & Unknowns - **[Unclear scope, possible regressions, missing reproduction info]** Recommend: [option] — [why] Discarded: [option] ([why not]) ``` ### Improvement / tech debt ```markdown ## Improve: [what's being improved] [1-2 sentence description of the improvement and why it matters now] **Current state**: [what exists today and what's wrong with it] **Desired state**: [what it should look like after] ### Strategic Fit [One line: "Serves bet: [name] — [how]" | "No current bet — [why it's worth doing anyway]" | "No durable product context in repo"] ### Acceptance Criteria - [Measurable outcomes — what changes for the user or the system] ### Rollout & Rollback [One of: "neither — direct deploy" | "expand-contract on [schema/API/interface]" | "flag at [boundary]" | "both"] [One-line reasoning. Most tech-debt work that changes a shared contract uses expand-contract alone.] ### Risks & Unknowns - **[Migration concerns, backwards compatibility, scope creep]** Recommend: [option] — [why] Discarded: [option] ([why not]) ``` Use the variant that fits best. For work that doesn't fit neatly, adapt — the acceptance criteria and risks sections are the essential parts. ## Examples ### Small work (single ticket) **Input**: "We need to show users how many items are in their cart in the header" **Output**: ```markdown ## Cart item count in header Display a badge on the cart icon so shoppers can see how many items are in their cart without opening it. ### Strategic Fit No current bet — table-stakes e-commerce affordance. Worth doing because its absence generates "did my item get added?" support contacts. ### Acceptance Criteria - Display a numeric badge on the cart icon in the site header - Badge shows total quantity of items (not unique products) - Badge is hidden when cart is empty (not "0") - Count updates immediately when items are added/removed - Badge is visible on all pages where the header appears ### Designs N/A — follow existing badge patterns in the UI ### Rollout & Rollback Neither — direct deploy. Additive UI badge, no contract changing, no behavior change to existing flows. Rollback: revert. ### Dev Harness Trivial — badge renders from cart state on every page; seed a cart (or add items in a dev store) and reload. No funnel, no fixtures needed. ### Risks & Unknowns - **Should the count persist across sessions for logged-out users?** Recommend: Yes, use localStorage — users expect cart to survive tab close. Discarded: Server-side session (adds auth dependency for anonymous users) - **Max display value for large carts?** Recommend: Show "99+" — standard e-commerce pattern, avoids layout overflow. Discarded: Unlimited display (breaks layout at 4+ digits) ``` ### Bug fix **Input**: "Users are complaining that the search doesn't find products by SKU" **Output**: ```markdown ## Fix: search doesn't match product SKUs Users expect to find products by entering a SKU in the search bar, but search currently only matches product names and descriptions. **Current behavior**: Searching "SKU-12345" returns no results even when the product exists. **Expected behavior**: SKU search returns the exact matching product. **Reproduction**: Go to search → enter any valid SKU → observe zero results. ### Acceptance Criteria - Search matches against the product SKU field in addition to name/description - Exact SKU match ranks first in results - Partial SKU matches are included but ranked lower ### Rollout & Rollback Direct deploy — bug fix, ships to everyone. If the index needs a new field, that's an expand-only schema change (additive, no contract phase needed). Rollback: revert. ### Risks & Unknowns - **Does the search index include the SKU field?** Recommend: Check index schema first — if SKU is missing, add it and rebuild. Rebuild is cheap if index is small. Discarded: Separate SKU lookup endpoint (fragments search UX into two paths) - **Are SKUs unique across all product types?** Recommend: Treat as unique — if duplicates exist, return all matches ranked by relevance. Discarded: Error on duplicate (punishes the user for a data quality issue) ``` ### Larger work (PRD-style) **Input**: "Partners aren't completing onboarding. We want to remind them." **Output**: ```markdown ## Onboarding reminder modal Display a reminder modal when a Partner logs into the Back Office without completing all onboarding steps. Partners who don't complete onboarding can't start earning — the modal lists what's missing and guides them to finish. ### Strategic Fit Serves bet: "activate signed-up Partners" — incomplete onboarding is the single largest drop-off between signup and first earning. ### Acceptance Criteria **When it appears:** - Partner logs into Back Office - Partner has at least one incomplete onboarding step **Modal content:** - Title: "Complete Your Profile To Start Earning" - Supporting text: "You're just a step away from unlocking your Back Office and getting paid." - Dynamic list of incomplete steps with clear labels: - Missing DOB → "Add your Date of Birth" - Missing SSN → "Add your SSN" - Missing Bank Info → "Add bank details" - Primary button: Takes user to Settings page to complete info - Close/dismiss icon to skip for now **Behavior:** - Modal appears on each login until onboarding is complete - Dismissing the modal does not block access to the Back Office ### Designs [Link to Figma designs] ### Rollout & Rollback Flag at the modal entrypoint (`onboarding_reminder_modal_enabled`) — user-visible behavior change some Partners may dislike, and the team wants a fast off-switch if support volume spikes. No contract changing. Discover flag system from `.tap/architecture.md`. Rollback: flag flip. ### Dev Harness No complex core, so no L1 needed — the requirement is reachability: incomplete-onboarding state must be *seedable* (seed script or fixture Partner), not only producible by abandoning a real signup. Then the modal is one login away on any dev account. ### Risks & Unknowns - **Should we limit how often the modal appears?** Recommend: Show every login — onboarding completion is a business requirement, not a preference. Dismissing = "not now", not "never". Discarded: Once per day (risks Partners forgetting entirely), once ever (defeats the purpose) - **What happens if a Partner dismisses repeatedly?** Recommend: No escalation — the modal is already the nudge. If they dismiss 10 times, they have a reason. Don't punish. Discarded: Escalating banner (adds annoyance without addressing root cause of non-completion) - **Are there any steps that should block Back Office access entirely?** Recommend: No blocking — partial access is better than no access. Partners who can see their dashboard are more motivated to complete onboarding. Discarded: Hard block after SSN/bank (creates support burden, Partners call asking why they're locked out) ``` ## Design Thinking When shaping, consult [references/software-design-philosophy.md](references/software-design-philosophy.md) for principles that help define work in ways that avoid unnecessary complexity. Key lenses: define errors out of existence, design the common case to be simple, flag information leakage risks. ## What NOT to include - Technical implementation details (database schemas, API designs, code patterns) - Harness implementation (script paths, commands, fixture formats) — the shape states harness *requirements*; the plan delivers the harness - Time estimates or sprint planning - Assigned developers or teams - Detailed test cases (those come later) Keep it focused on *what* needs to exist and *why*, not *how* to build it. ## Handoffs - Shaped work feeds into `/dev-skills:implementation-planning` for technical design. - If the repo had no `.tap/product.md`, mention `/tap-skills:curate-product-context` once — every shape after it can state strategic fit against something real. - Offer to publish the shape doc for team review: `/tap-skills:render-doc` then `/tap-skills:dossier-publish` (md stays source of truth; republish after edits).