---
name: shared-understanding
description: Turn messy notes, voice transcripts, Slack threads, and unstructured product ideas into clear, plain-language product briefs ready for engineers or coding agents to decompose. Strip corporate PRD bloat, preserve concrete human context, separate locked decisions from open questions, define hard boundaries and non-goals, and break work into thin vertical slices. Use whenever a user dumps rough thoughts, brainstorms, call notes, or half-formed feature ideas and wants a clear spec, engineering handoff, epic brief, feature one-pager, or agent-ready plan.
metadata:
  author: Andrew Durden
  version: 1.1.0
  visibility: public
  website: https://andrewdurden.com/skills/shared-understanding/SKILL.md
license: MIT
---
# Shared Understanding

Shared understanding beats exhaustive documentation. Handing engineers or coding agents a ten-page wall of corporate jargon buries real constraints in filler, hides unanswered questions, and leaves everyone picturing a different product anyway. Use this workflow to turn messy brain-dumps, call notes, voice memos, and scattered threads into a plain-language brief that preserves every boundary needed for clean technical decomposition.

## When to Use (and When to Shorten or Skip)

- **Use in full:** Translating unstructured founder/PM notes, call transcripts, or Slack threads into an aligned epic brief for an engineering squad or coding agent.
- **Shorten to a 4-bullet PR note:** Single-engineer bug fixes, copy updates, or sub-day UI polish where a full 5-section brief creates more ceremony than clarity.
- **Calibration over rigid word caps:** Aim for roughly 300 to 600 words on single-feature briefs so the whole team actually reads it, while allowing complex multi-system migrations or compliance specs whatever tables and appendices accuracy requires.

## Noise-to-Clarity Workflow

- [ ] Step 1: Sort raw noise into confirmed facts, concrete human friction, and open decisions
- [ ] Step 2: Write the Before-and-After human story in plain everyday speech
- [ ] Step 3: Lock the fence posts (invariants, unhappy states, and explicit non-goals)
- [ ] Step 4: Break delivery into 2 to 4 thin, end-to-end vertical slices
- [ ] Step 5: Cut buzzwords and any sentence that does not change a build or design decision

### Step 1: Separate Signal From Unmade Decisions

Sort messy input into three buckets before drafting requirements:

1. **Confirmed constraints and facts:** Deadlines, existing API limits, legal rules, or commitments explicitly stated in the source notes.
2. **Vivid human context:** Specific moments of friction, direct user quotes, and device or environment realities. Keep one concrete example intact rather than abstracting it into generic personas.
3. **Open decisions (quarantine, never invent):** Wherever the raw notes stay silent on an edge case or policy rule, do **not** invent silent requirements. List each gap under `Open Decisions` with a proposed default and a one-line rationale so the owner can approve or override it quickly.

### Step 2: Write a Plain-Language Before-and-After Story

Skip robotic templates (`As an authenticated user, I want an optimized workflow so that efficiency increases`) that hide why the work matters:

- **Bloated PRD jargon (avoid):** "Leverage unified cross-channel state orchestration to streamline multi-party reservation modifications."
- **Plain human clarity (prefer):** "Today, when two families traveling together want to move dinner by 30 minutes, they have to cancel both bookings and hope nobody grabs one table mid-refresh. After this change, either family can shift the linked time in one tap, and the system moves both tables together or leaves the original booking untouched."

Use **one consistent noun** for each domain object from top to bottom.

### Step 3: Lock the Fence Posts Without Dictating Internal Code

1. **Hard invariants:** Exact rules around money, permissions, privacy, data integrity, or latency targets (using concrete numbers where known, and marking targets as `to validate` when unmeasured).
2. **Empty, slow, and unhappy states:** What renders on first visit with zero saved items, when an upstream service times out, or when a user taps submit twice on spotty mobile reception.
3. **Explicit Non-Goals:** Two to four adjacent temptations deliberately excluded from this build so scope does not sprawl mid-sprint.

### Step 4: Shape Thin Vertical Slices for Decomposition

Avoid horizontal layer handoffs (`Slice 1: DB`, `Slice 2: API`, `Slice 3: UI`) that hide integration surprises until the end:

| Slice Tier | Purpose | Example Scope |
| :--- | :--- | :--- |
| **Slice 1: Walking Spine** | Proves the primary user path works end-to-end with real data and core invariants | Single user completes the happy path + safe rollback on error |
| **Slice 2: Real-World Edges** | Handles production messiness before broad rollout | Empty state, timeout retry UX, duplicate-tap guard, and telemetry |
| **Slice 3: Fast-Follow Polish** | Optional convenience once the core loop holds up | Batch actions, keyboard shortcuts, or secondary preferences |

### Worked Example Where This Skill Leads to Doing Less

- **Messy Input:** A 25-message Slack thread debating a new multi-role permissions matrix, audit export CSV, and custom webhook builder for internal beta testers.
- **Shared-Understanding Compression:** Locking `Explicit Non-Goals` revealed all 12 beta testers sit on one internal Slack channel; shipping **Slice 1 alone** (read/write toggle + existing server logs) let the team launch two weeks earlier and drop the unused webhook builder altogether.

## Output Template

```markdown
# [Plain-Language Feature Title]

## 1. The Human Problem (Before -> After)
- **Who & Moment:** [Specific user and real-world situation]
- **Today (Before):** [What happens right now and why it hurts]
- **After This Ships:** [What changes in plain everyday speech]
- **Outcome Signal:** [1 to 2 observable user or system behaviors]

## 2. Boundaries & Non-Goals
- **Must-Keep Invariants:** [Trust, auth, privacy, data, or latency rules]
- **Explicit Non-Goals:** [Adjacent features deliberately excluded right now]

## 3. States & Edge Cases
| Scenario | Expected System & User Behavior |
| :--- | :--- |
| **First-Time / Empty** | [What renders before user data exists] |
| **Core Happy Path** | [Input -> state update -> visible confirmation] |
| **Failure / Timeout / Conflict** | [Safe recovery without losing user work] |

## 4. Vertical Slices
1. **Slice 1 (Walking Spine):** [Smallest end-to-end working flow + check]
2. **Slice 2 (Real-World Edges):** [Unhappy paths, permissions, and logging]
3. **Slice 3 (Optional Polish):** [Deferrable enhancements]

## 5. Open Decisions & Missing Evidence
- **[Open Call 1]:** Proposed default is `[Default]` because `[Reason]`.
- **Unverified Assumption:** [What still needs quick technical or user verification]
```

## Verification Check

1. **Zero Buzzword Filler:** Strip words like `seamless`, `intuitive`, `synergistic`, `leverage`, and `streamline` in favor of testable specifics.
2. **Consistent Noun Dictionary:** Confirm every domain concept uses one exact name throughout.
3. **No Silent Policy Inventions:** Confirm every detail absent from the raw input sits openly under `Open Decisions`.

## Gotchas

- **Polishing away the concrete story:** Keep one specific real-world example in Section 1 so engineers and designers see the edge cases intuitively.
- **Confusing length with alignment:** Put multi-table schemas in linked technical appendices so the top brief stays readable in one sitting.
