references/complexity_matching.md
7.7 KB查看排版效果| 1 | # Complexity Matching — Compressed vs Full 4-Section Output |
| 2 | |
| 3 | This reference answers exactly one decision: **when does capture use the full 4-section format vs the compressed format, and what does each look like in practice?** |
| 4 | |
| 5 | Pair with `scripts/complexity_estimator.py` for the deterministic recommendation. |
| 6 | |
| 7 | ## The Core Rule |
| 8 | |
| 9 | > **Match output complexity to input complexity.** |
| 10 | |
| 11 | A 30-item dump with natural clusters needs the full 4-section structure to be useful. A 5-item dump of unrelated todos drowns in that structure — the format becomes ceremony, not signal. Force-fitting structure on a small dump makes the skill feel bureaucratic. |
| 12 | |
| 13 | ## When to Use Each Format |
| 14 | |
| 15 | | Signal | Recommended format | |
| 16 | |---|---| |
| 17 | | 8+ items AND natural clustering exists (3+ items share a theme) | Full 4-section | |
| 18 | | 8+ items but NO clustering (all unrelated todos) | Compressed (with explicit "no clusters" note) | |
| 19 | | 5–7 items, mixed kinds, some clustering | Either — judgment call. Lean compressed unless clusters are strong. | |
| 20 | | ≤5 items, unrelated | Compressed | |
| 21 | | ≤5 items but all related to one project | Compressed with single project header | |
| 22 | | Workspace inaccessible AND ≤5 items | Compressed with no Section 3 (still note "no workspace accessible") | |
| 23 | |
| 24 | `complexity_estimator.py` returns `format=full` or `format=compressed` based on item count + clustering signal. Use it as the seed; override with judgment when context warrants. |
| 25 | |
| 26 | ## Format A: Full 4-Section |
| 27 | |
| 28 | Use for substantive dumps with real structure. Roughly: |
| 29 | |
| 30 | ``` |
| 31 | ## Projects & Ideas |
| 32 | |
| 33 | ### {Project A in user's voice} |
| 34 | - {component} |
| 35 | - {component} |
| 36 | - Q: {open question} |
| 37 | - Decide: {decision} |
| 38 | |
| 39 | ### {Project B} |
| 40 | - ... |
| 41 | |
| 42 | ## Tasks |
| 43 | |
| 44 | - {task} [Project: A] |
| 45 | - {task} |
| 46 | - Decide: {decision} |
| 47 | - Resolve: {open question} |
| 48 | |
| 49 | ## Connections |
| 50 | |
| 51 | - {file/folder}: {real workspace match} |
| 52 | - (or) "No connections found — workspace inventory clean." |
| 53 | - (or) "No workspace accessible from here..." |
| 54 | |
| 55 | ## How I Can Help |
| 56 | |
| 57 | - {concrete offer: what + where} |
| 58 | - {concrete offer: what + where} |
| 59 | |
| 60 | **Which of these should I tackle?** |
| 61 | ``` |
| 62 | |
| 63 | ## Format B: Compressed |
| 64 | |
| 65 | Use for small or unrelated dumps. Roughly: |
| 66 | |
| 67 | ``` |
| 68 | ## What I heard |
| 69 | |
| 70 | - {item} |
| 71 | - {item} |
| 72 | - {item} |
| 73 | - Decide: {decision} |
| 74 | - Resolve: {open question} |
| 75 | |
| 76 | ## How I can help |
| 77 | |
| 78 | - {concrete offer: what + where} |
| 79 | - {concrete offer: what + where} |
| 80 | |
| 81 | Which should I tackle? |
| 82 | ``` |
| 83 | |
| 84 | Notice what's gone in compressed: |
| 85 | - No project headers (nothing to cluster) |
| 86 | - No separate Tasks section (the list IS the tasks) |
| 87 | - No Connections section as a separate header (if there's a real connection, fold it inline as a parenthetical: `- fix the auth bug (relates to src/auth/login.ts:42)`) |
| 88 | - Same Section 4 discipline (concrete offers + directive question) |
| 89 | |
| 90 | ## Worked Examples |
| 91 | |
| 92 | ### Example 1: Full 4-section (12 items, 2 clusters) |
| 93 | |
| 94 | **Dump:** |
| 95 | > "Ok so dump time. Q3 launch is approaching — need to nail down pricing, draft the launch email, brief Sarah on the marketing angle. Also ferret app keeps nagging me — should I talk to my cofounder about it, or is it just procrastination? Need to sketch the matching algorithm if it's serious. Also: fix the damn auth bug, rewrite the login form because it's ugly, write tests for both. Oh and I should probably do my Q3 OKRs before launch." |
| 96 | |
| 97 | **Extracted items:** 11 |
| 98 | **Clusters:** Q3 Launch (4 items), Ferret App (3 items), Auth (3 items), OKRs (1 item) |
| 99 | **Recommendation:** `format=full` (clear clustering, 11 items) |
| 100 | |
| 101 | **Output:** |
| 102 | |
| 103 | ``` |
| 104 | ## Projects & Ideas |
| 105 | |
| 106 | ### Q3 Launch |
| 107 | - Nail down pricing |
| 108 | - Draft launch email |
| 109 | - Brief Sarah on the marketing angle |
| 110 | - Decide: Q3 OKRs (do before launch) |
| 111 | |
| 112 | ### Ferret App |
| 113 | - Talk to cofounder OR decide it's procrastination |
| 114 | - Sketch matching algorithm (if serious) |
| 115 | - Decide: serious project or shelf? |
| 116 | |
| 117 | ### Auth Fixes |
| 118 | - Fix the auth bug |
| 119 | - Rewrite the login form (it's ugly) |
| 120 | - Write tests for the bug fix + login rewrite |
| 121 | |
| 122 | ## Tasks |
| 123 | |
| 124 | - Nail down Q3 pricing [Project: Q3 Launch] |
| 125 | - Draft Q3 launch email [Project: Q3 Launch] |
| 126 | - Brief Sarah on Q3 marketing angle [Project: Q3 Launch] |
| 127 | - Talk to cofounder about ferret app [Project: Ferret App] |
| 128 | - Sketch ferret matching algo [Project: Ferret App] |
| 129 | - Fix auth bug [Project: Auth Fixes] |
| 130 | - Rewrite login form [Project: Auth Fixes] |
| 131 | - Write tests for auth + login [Project: Auth Fixes] |
| 132 | - Do Q3 OKRs (before launch) |
| 133 | - Decide: ferret app — serious or shelf? |
| 134 | |
| 135 | ## Connections |
| 136 | |
| 137 | (workspace inventory results go here — only verified matches) |
| 138 | |
| 139 | ## How I Can Help |
| 140 | |
| 141 | - I can draft the Q3 launch email as a 1-pager. Output: chat reply. |
| 142 | - I can pull together a pricing-options matrix from your existing pricing docs. Output: `docs/q3-pricing-options.md`. |
| 143 | - I can scaffold the ferret matching algorithm sketch (input → match score). Output: `docs/ferret-algo-sketch.md`. |
| 144 | |
| 145 | **Which of these should I tackle?** |
| 146 | ``` |
| 147 | |
| 148 | ### Example 2: Compressed (5 unrelated items) |
| 149 | |
| 150 | **Dump:** |
| 151 | > "Quick: email Sarah, fix that test that's been flaky, decide between Postgres and Mongo for the new service, dentist appointment, finish reading the article on RAG." |
| 152 | |
| 153 | **Extracted items:** 5 |
| 154 | **Clusters:** none (all unrelated) |
| 155 | **Recommendation:** `format=compressed` |
| 156 | |
| 157 | **Output:** |
| 158 | |
| 159 | ``` |
| 160 | ## What I heard |
| 161 | |
| 162 | - Email Sarah |
| 163 | - Fix the flaky test |
| 164 | - Decide: Postgres or Mongo for the new service |
| 165 | - Dentist appointment |
| 166 | - Finish reading the RAG article |
| 167 | |
| 168 | ## How I can help |
| 169 | |
| 170 | - I can draft the email to Sarah if you tell me what it's about. Output: chat reply. |
| 171 | - I can investigate the flaky test (likely racing condition; happy to reproduce). Output: chat analysis + fix PR if you want. |
| 172 | - I can pull a Postgres-vs-Mongo decision matrix scoped to your service requirements. Output: chat reply or `docs/db-decision.md`. |
| 173 | |
| 174 | Which should I tackle? |
| 175 | ``` |
| 176 | |
| 177 | Notice the dentist appointment + RAG article aren't in "How I can help" — there's nothing meaningful to offer on those. That's correct: don't pad Section 4 with offers for things that don't need help. |
| 178 | |
| 179 | ### Example 3: Compressed but workspace-aware (small + connection inline) |
| 180 | |
| 181 | **Dump:** |
| 182 | > "auth bug is back, need to look at the login flow again, also I want to add 2FA finally." |
| 183 | |
| 184 | **Extracted items:** 3 |
| 185 | **Clusters:** all auth-related but only 3 items |
| 186 | **Recommendation:** `format=compressed` |
| 187 | |
| 188 | **Output:** |
| 189 | |
| 190 | ``` |
| 191 | ## What I heard (Auth) |
| 192 | |
| 193 | - Auth bug is back (relates to `src/auth/login.ts` based on workspace inventory) |
| 194 | - Look at login flow again |
| 195 | - Add 2FA |
| 196 | |
| 197 | ## How I can help |
| 198 | |
| 199 | - I can reproduce the auth bug from the symptoms — what's the failure mode? Output: chat repro + fix. |
| 200 | - I can sketch a 2FA implementation matching your existing auth pattern (TOTP via the same provider you use). Output: `docs/2fa-sketch.md`. |
| 201 | |
| 202 | Which should I tackle? |
| 203 | ``` |
| 204 | |
| 205 | Notice the workspace connection got folded inline as a parenthetical instead of a separate Section 3 header. That's the compressed-with-context pattern. |
| 206 | |
| 207 | ## Operational Checklist |
| 208 | |
| 209 | Before delivering output: |
| 210 | |
| 211 | - [ ] Run `complexity_estimator.py` (or apply the Signal table above) |
| 212 | - [ ] If `format=compressed`, do NOT force the 4-section format |
| 213 | - [ ] If `format=full`, ensure the clusters are real (3+ items per cluster) — don't invent clusters to fill the format |
| 214 | - [ ] Either way, Section 4 ("How I can help") MUST have concrete offers with what + where |
| 215 | - [ ] Either way, end with the directive question |
| 216 | |
| 217 | ## Why This Matters |
| 218 | |
| 219 | A skill that returns the same format regardless of input is a template, not a skill. The reason capture is useful is that it adapts to the dump's actual shape. When a 5-item list comes back wrapped in 4 elaborate empty-feeling sections, the user learns to distrust the skill. When a 30-item dump comes back as a flat compressed list, the user learns the skill can't actually handle complexity. |
| 220 | |
| 221 | Match the output to the input, every time. |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
