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:

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 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

## [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

## 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

## 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:

## 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:

## 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:

## 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 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).