From 45b5e5c2b3f4e688820f95d211c5acee6cc59e48 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Sun, 26 Apr 2026 23:31:54 +0900 Subject: [PATCH] docs: add docs/PINPOINT_FILING_GUIDE.md with #290 worked example --- README.md | 2 +- docs/PINPOINT_FILING_GUIDE.md | 101 ++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 docs/PINPOINT_FILING_GUIDE.md diff --git a/README.md b/README.md index 845e40e..278b145 100644 --- a/README.md +++ b/README.md @@ -218,7 +218,7 @@ We welcome contributions! Before filing an issue or pull request: - **Supported providers:** See [docs/SUPPORTED_PROVIDERS.md](./docs/SUPPORTED_PROVIDERS.md) - **For security issues:** See [SECURITY.md](./SECURITY.md) - **For bug reports / features:** Check [ROADMAP.md](./ROADMAP.md) to see if it's already pinpointed -- **How to file a pinpoint:** See [CONTRIBUTING.md](./CONTRIBUTING.md) for the exact format +- **How to file a pinpoint:** See [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Pinpoint Filing Guide](./docs/PINPOINT_FILING_GUIDE.md) - **Issue templates:** Use [.github/ISSUE_TEMPLATE/pinpoint.md](./.github/ISSUE_TEMPLATE/pinpoint.md) ## Ownership / affiliation disclaimer diff --git a/docs/PINPOINT_FILING_GUIDE.md b/docs/PINPOINT_FILING_GUIDE.md new file mode 100644 index 0000000..a5cb1d5 --- /dev/null +++ b/docs/PINPOINT_FILING_GUIDE.md @@ -0,0 +1,101 @@ +# Pinpoint Filing Guide + +This guide walks through the workflow for filing a new claw-code pinpoint, from initial friction to merged ROADMAP entry. For format details, see [CONTRIBUTING.md](../CONTRIBUTING.md). For issue template, see [.github/ISSUE_TEMPLATE/pinpoint.md](../.github/ISSUE_TEMPLATE/pinpoint.md). + +## What is a Pinpoint? + +A pinpoint is a precise, distinct claw-code clawability gap captured in ROADMAP.md format. Pinpoints differ from generic issues by: +- **Specificity:** Exact file paths, function names, line numbers when available +- **Distinctness:** Verified not already covered by existing pinpoints +- **Live evidence:** Real friction event, not hypothetical +- **Fix shape:** Concrete delta proposal, not vague "should improve X" + +## Workflow + +### Step 1: Identify friction + +Use claw-code in real work. When you hit friction (slow startup, broken behavior, opaque error, missing feature, test brittleness, etc.), STOP and capture: +- What you were trying to do +- What you expected to happen +- What actually happened +- Exact error message / log output (verbatim) + +### Step 2: Identify distinct axis + +Open ROADMAP.md and search for related existing pinpoints (use the [Cluster Index](../ROADMAP.md#pinpoint-cluster-index)). + +For each candidate match: +- Does the existing pinpoint cover this exact symptom? +- Does it cover this exact axis (e.g., timing vs envelope vs config)? +- Is your case a SUBSET, a SUPERSET, or an ORTHOGONAL axis? + +If your case is orthogonal, file new. If subset, add live-evidence as additional context to existing pinpoint. If superset, file new + cross-reference existing. + +### Step 3: Verify with code + +Before filing, look at the relevant source code: +- `rust/crates/api/src/sse.rs` — provider routing +- `rust/crates/runtime/src/conversation.rs` — auto-compaction logic +- `rust/crates/rusty-claude-cli/src/main.rs` — CLI entry +- Search with grep / ripgrep to find the relevant module + +If the code clearly does NOT have the feature you expected, file a pinpoint. If the code DOES have the feature but it's broken, file a bug. + +### Step 4: Write the entry + +Follow the canonical 5-section format (see [CONTRIBUTING.md](../CONTRIBUTING.md)): +1. **Exact pinpoint** — One precise sentence +2. **Live evidence** — Real friction event with timestamps +3. **Why distinct** — Explicit comparison to nearest existing pinpoints +4. **Concrete delta** — What you're filing (e.g., "ROADMAP.md appended") +5. **Fix shape recorded** — Bullet list of suggested implementation steps + +### Step 5: Submit + +Append to ROADMAP.md and commit: + +``` +git add ROADMAP.md +git commit -m "roadmap: # filed ()" +git push origin +git push fork +``` + +Verify three-way parity (local == origin == fork) before posting any update. + +## Worked Example: #290 (stream-init failure envelope) + +This shows how #290 was filed in real-time on 2026-04-26. + +### Step 1: Friction identified + +gaebal-gajae's session hit `500 empty_stream: upstream stream closed before first payload` repeatedly (4x in 30 min). Bare-string error surfaced; no diagnostics, no retry guidance. + +### Step 2: Distinct axis identified + +- #266 (typed-error-kind taxonomy) covers single-failure categorization, NOT stream-init specifically +- #287 (auto-compaction reactive) covers session-size failures, NOT transport +- #288 (JSON envelope failure) covers context-window envelope, NOT stream-init + +→ Orthogonal: filed new #290 covering typed-stream-init-failure-envelope + +### Step 3: Code verified + +Inspected `rust/crates/api/src/sse.rs` — confirmed no `failure_class=upstream_stream_init` discriminant, no retry recommendation in JSON envelope. + +### Step 4: Entry written + +Used canonical 5-section format. Listed 4 live evidence timestamps. Cross-referenced #266, #287, #288 in "Why distinct." + +### Step 5: Submitted + +Commit `0f38975`, pushed to both origin and fork, parity verified, Discord post under 1500 chars. + +**Total time: ~2 minutes from friction identification to merged ROADMAP entry.** + +## Tips + +- **File while it's fresh.** Wait too long and you'll forget exact symptoms. +- **Check Cluster Index FIRST** — saves time vs scanning full ROADMAP. +- **Write Fix Shape even if you don't implement.** Helps future contributors. +- **Live evidence with timestamps > theoretical examples.** Real-world friction always wins.