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

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]

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

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

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

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

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

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

### 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-planning for technical design.