references/workspace_detection.md
4.9 KB查看排版效果| 1 | # Workspace Detection Tactics |
| 2 | |
| 3 | This reference answers exactly one decision: **how does the capture skill verify Section 3 connections without fabricating them, across the four contexts the skill might run in?** |
| 4 | |
| 5 | Pair with `scripts/workspace_inventory.py` for the deterministic Glob+Grep implementation. |
| 6 | |
| 7 | ## The Core Rule |
| 8 | |
| 9 | Section 3 ("Connections") earns the skill its keep. It also breaks the skill faster than anything else if it lies. The rule: |
| 10 | |
| 11 | > **Only surface connections that were actually verified by Glob, Grep, Read, or an equivalent retrieval call this turn.** |
| 12 | |
| 13 | If you can't verify, you say "no workspace accessible" or "no connections found" — never invent something plausible-sounding. |
| 14 | |
| 15 | ## Context 1: Claude Code CLI (filesystem-native) |
| 16 | |
| 17 | **Tools available:** `Glob`, `Grep`, `Read`, `Bash`. |
| 18 | |
| 19 | **Tactics, in order:** |
| 20 | |
| 21 | 1. **Extract keywords from the dump.** Pull domain nouns, project names, file-format hints (`.md`, `.py`, `auth`, `consensus`, `pricing`). |
| 22 | 2. **Glob for filename matches.** `Glob("**/*{keyword}*")` for each keyword. Limit to top-N matches per keyword to avoid noise. |
| 23 | 3. **Grep for content matches.** `Grep("{keyword}")` constrained to source extensions. |
| 24 | 4. **Read the top-level structure.** `Bash("ls -la")` and `Bash("find . -maxdepth 2 -type d | head -30")` to surface relevant folders. |
| 25 | 5. **Stitch the matches into Section 3 entries.** Each entry: `- {file or folder}: {how it relates to dump item N, with evidence}`. |
| 26 | |
| 27 | **Example output:** |
| 28 | |
| 29 | ``` |
| 30 | ## Connections |
| 31 | |
| 32 | - `engineering/grill-me/` — relates to your "build a grill skill" dump item (folder exists, has plugin.json + SKILL.md). Likely the template you'd want to mirror. |
| 33 | - `megaprompts/05-capture-megaprompt.md` — relates to your "convert capture spec to skill" item. The spec file is here. |
| 34 | - `documentation/implementation/` — empty directory, but the location for the implementation plan you mentioned. |
| 35 | ``` |
| 36 | |
| 37 | **What NOT to do:** |
| 38 | - "There's probably a config for that somewhere" — speculation, no verification. |
| 39 | - "Your project likely has an auth module" — guess, no Glob. |
| 40 | - "I see you might have considered X before" — projection, no Grep. |
| 41 | |
| 42 | ## Context 2: Claude.ai with project knowledge |
| 43 | |
| 44 | **Tools available:** Project-knowledge file list, file content reads. |
| 45 | |
| 46 | **Tactics:** |
| 47 | |
| 48 | 1. **List the project knowledge files** — at the start of the run, get the file inventory. |
| 49 | 2. **Match by title keyword** — for each dump keyword, find files whose titles contain it. |
| 50 | 3. **Open the top matches** and check if the content is actually related (not just title coincidence). |
| 51 | 4. **Surface only the verified matches** in Section 3. |
| 52 | |
| 53 | **What NOT to do:** |
| 54 | - Cite a file you didn't open — title match alone is not enough. |
| 55 | - Claim a file says X without quoting evidence. |
| 56 | |
| 57 | ## Context 3: Connected tools (Notion, Drive, GitHub, Slack via MCP) |
| 58 | |
| 59 | **Tools available:** Whatever MCP tools the harness has registered for the user's connected services. |
| 60 | |
| 61 | **Tactics:** |
| 62 | |
| 63 | 1. **Check tool availability first** — list the MCP tools surfaced for this session. If no Notion/Drive/GitHub MCP is registered, skip this context. |
| 64 | 2. **Search via MCP** — use the search tool for each tool with dump keywords. |
| 65 | 3. **Surface verified hits** with the link / ID returned by the tool. |
| 66 | |
| 67 | **What NOT to do:** |
| 68 | - Reference a Notion page that wasn't returned by the search. |
| 69 | - Cite a GitHub issue number without confirming via the GitHub MCP. |
| 70 | |
| 71 | ## Context 4: No accessible workspace |
| 72 | |
| 73 | **Signals you're in this context:** |
| 74 | - No filesystem tools loaded |
| 75 | - No project knowledge attached |
| 76 | - No workspace MCPs registered |
| 77 | - `workspace_inventory.py` returns empty + you can't verify any other way |
| 78 | |
| 79 | **Required behavior:** |
| 80 | |
| 81 | State the limitation explicitly. Ask about the user's setup. Do NOT fabricate connections. |
| 82 | |
| 83 | **Template output:** |
| 84 | |
| 85 | ``` |
| 86 | ## Connections |
| 87 | |
| 88 | No workspace accessible from here, so this section is empty. If you're running |
| 89 | this from Claude Code or have a project with files attached, I can fill it in. |
| 90 | |
| 91 | Want to share where this work lives — a repo path, a Notion workspace, an |
| 92 | attached project? I can re-run the connections pass with that context. |
| 93 | ``` |
| 94 | |
| 95 | ## Operational Checklist (Per Run) |
| 96 | |
| 97 | - [ ] Extract dump keywords (domain nouns, project names, format hints) |
| 98 | - [ ] Determine context (CLI / web project / MCP-connected / inaccessible) |
| 99 | - [ ] Run the context-appropriate tactics; never skip verification |
| 100 | - [ ] If context is "inaccessible", say so explicitly + ask about setup |
| 101 | - [ ] Each Section 3 entry must cite the evidence (filename matched, search hit, etc.) |
| 102 | - [ ] Zero entries with phrasing like "probably", "likely", "you might have" — those are speculation, not connections |
| 103 | |
| 104 | ## Why This Matters |
| 105 | |
| 106 | The single fastest way to lose user trust in capture is to surface a fabricated connection. Once the user catches one — "wait, that file doesn't exist" — they stop trusting the entire output, including the items that were correct. Verification is cheap; fabrication is expensive. |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
