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
- 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.
- 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 CLAUDE.md or similar to understand what the application does (the product, not technical details).
- Shape the work — Write the definition using the output format below. Pick the template variant that fits the type of work.
- 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.
- 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, and risks/unknowns. The middle sections flex based on what you're shaping.
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 "useMath.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
## [Clear, descriptive title]
[1-2 sentence description of what this feature does, who it's for, and why it matters]
### 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"]
### Risks & Unknowns
- **[Question or risk]**
Recommend: [option] — [why]
Discarded: [option] ([why not])Bug fix
## 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]
### Risks & Unknowns
- **[Unclear scope, possible regressions, missing reproduction info]**
Recommend: [option] — [why]
Discarded: [option] ([why not])Improvement / tech debt
## 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]
### Acceptance Criteria
- [Measurable outcomes — what changes for the user or the system]
### 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:
## 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.
### 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
### 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:
## 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
### 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:
## 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.
### 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]
### 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 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)
- 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-planningfor technical design.