check-my-stack

Files (6)

• SKILL.md
• output-template.md · references/
• reconcile.sh · scripts/
• plain-language-presentation.test.sh · scripts/tests/
• 2026-07-05-check-my-stack-v2-review.md · specs/
• 2026-07-05-v2-redesign-spec.md · specs/

SKILL.md (first lines)

<!-- 本檔在契約測試底下：bash ~/.claude/skills/check-my-stack/scripts/tests/plain-language-presentation.test.sh；python3 ~/.claude/commands/tests/test_skill_verify_one_shot_callers.py -->

# Competitive Stack Analysis

A tool reaches this skill because the user found it interesting enough to bring — the input is pre-filtered by their interest. The job is therefore: **build the strongest adoption hypothesis for the tool first, then try to break it**. There is no default verdict; only the analysis order has a default. This posture governs effort allocation (search hard for a path to value before rejecting), not the evidence standard (claims need the same proof either way).

## Governing rule (order is mandatory)

Enumerate the user's existing stack maturity FIRST → then map the tool point-by-point onto it. Never "list the tool's highlights first, then back-fill where the user could apply them" — reading the README first anchors the whole analysis on the tool's marketing framing. Every borrow candidate's real value = capability ÷ maturity of the user's existing equivalent, whichever way the arithmetic lands.

## Workflow

### Step 0 — Fast-kill check (the only paper-verdict shortcut)

Two qualifying routes; the qualification evidence goes into the Gate Ledger (Step 6.4):

- **(a) Settled rejection lineage hit** — all three required, because a lineage citation without them is exactly how stale verdicts self-perpetuate: (1) cite the lineage entry by name; (2) one sentence arguing this case's frame is the same shape as the lineage's frame; (3) mini-reconcile the entry (is the denominator behind that rejection still in place? any major upstream change in the tool?). Old entries without a frame count as leads, not qualification — annotate the frame when citing (incremental migration). An `exhausted` marker (Step 6.6) qualifies; overturning it needs new delta evidence.
- **(b) Structural dealbreaker hit** — cite the discipline entry (billing can't ride an existing subscription / agent-in-loop vs background-scraper mismatch / mission-critical environment incompatibility) + one sentence of applicability.

There is deliberately no "already covered by my superset" route here: that judgment needs Step 1's inventory, which hasn't run yet — calling it from memory of the stack is the anchoring failure this skill exists to prevent. Superset kills emerge naturally after Step 3.

Neither route qualifies → run the default path, Steps 1-6.

**Narrow-scope re-invocation** — when the user explicitly limits scope (e.g. "只評估這幾條規則、不要重做整個 repo 研究"), Blocks 1-4 may be skipped, but never the accounting: the output must still end with a minimal ledger — one line stating the declared scope and which gates were skipped because of it, plus a Verdict line naming the evidence the judgment rests on. A narrow answer with zero ledger is unauditable afterward (this exact hole showed up in the 2026-07-20 i-have-adhd re-invocation). Then run Step 7 Self-Verify as usual — R4 has a matching exception.

**退役／缺口盤點路徑** — when the user asks what remains missing before retiring or replacing an existing pack, run the full Steps 1–6 but change the presentation shape. The chat main report is exactly `缺什麼／哪些已對應／退役前做哪三件`; 完整 Blocks 1–4 與 Gate Ledger 寫入證據副檔。This is not a narrow-scope shortcut: analysis and accounting stay complete, and Step 7 verifies the combined main-report-plus-sidecar draft.

### Step 1 — Inventory the existing stack (HARD GATE), then reconcile load-bearing rows

Before reading the tool's README / feature list, dispatch a **deep-explore agent** to enumerate what the user already has in the tool's domain and how mature each piece is. Do not inline this; the fan-out spans many files. Inventory targets (adapt to domain): settings.json hooks + `~/.claude/hooks/`, `~/.claude/skills/` + `~/.claude/commands/`, automation pipelines (launchd / cron / local-analysis routines), memory + wiki system, installed plugins/agent suites, project CLAUDE.md — and tools the user **tried and removed** in this domain with the documented reason (the strongest signal of what does not fit). For each capability: name the concrete mechanism precisely, maturity, current status.

Then reconcile **only the load-bearing rows** — the 2-4 rows whose maturity will be cited as a divisor in Block 2 or in the verdict. Reconciling the whole table is expensive and invites rubber-stamping; a stale row no decision rests on is harmless. Probe by capability type:

- CLI tool → `scripts/reconcile.sh <name>` (install state across PATH/uv/npm/brew/pipx + self-stack references)
- skill / agent → session jsonl invoke counts (file existence never counts as adoption — agents marked "mature" have turned out to have 0 spawns)
- hook → its audit/trace log
- scheduled job → launchd/cron last-run

Mark each reconciled row `install-verified` and/or `adoption-verified`; a row that fails either check gets its honest label ("installed, adoption unverified") instead of "mature". Done → Step 2.

### Step 2 — The tool's real value props, health, and precedent recall

Use research-before-answer discipline (personal wiki + memory recall in parallel with external `gh` / docs / web). Separate substance from marketing — star count, i18n, badges, sponsor funnels are not capabilities. Capture: actual mechanism, distribution model, license, activity, maintainer concentration.

Precedent recall is calibration, not ammunition: grep the memory store for **prior tool-evaluation cases with any outcome**, and pick the nearest by shape (tool type + claim structure), not by verdict direction — a calibration set that only ever cites rejections is a one-way ratchet. Before citing a precedent, check it still holds and state one of: holds / partially stale / stale (citation and write-back rules live in the memory file's 帳本記錄格式 section — the SSOT; follow it rather than restating it here). If the grep finds nothing, say "no prior precedent retrieved" — never invent a precedent to fill the slot. Done → Step 3.

### Step 3 — Point-by-point ÷ maturity mapping

For each tool capability, ask "does the user already have an equivalent, and at what maturity?" — map before judging. Each row's quotient is a conclusion, stated honestly whichever way it lands: `≈0` (existing equivalent at least as good), `<0` (re-litigates a settled rejection — flag explicitly), or `non-zero` (carries to Block 4). Done → Step 4.

### Step 4 — Best-frame search, with the pain gate

The tool's own marketing frame is only one candidate. Search the user's stack for the frame where the tool would land best. Three guardrails:

1. A frame must anchor to a **named Block 1 capability area** — invented frames can't be checked against anything.
2. Every candidate frame passes the **pain-vs-absence check**: name which Block 1 gap it closes or which divisor it upgrades. An uncovered area nobody has felt as pain is absence, not a gap — "the tool covers X and you don't have X" is not by itself a reason to adopt.
3. At most one alternative frame beyond the tool's own; "none found" is a legal and common answer.

Lesson this step exists for: graphify's winning frame (brownfield structural signal) was never proposed during its analysis — the user hit it themselves 12 days after a "definitive" rejection. Done → Step 5.

### Step 5 — Draft the verdict direction; extraction hunt on rejection drafts

Draft where this is heading: adopt / trial / extract / watch-defer / landscape. Heading to adopt or trial → skip the hunt (the whole tool is coming; nothing to steal separately) and go to Step 6. Heading to rejection/landscape → hunt for extractable pieces now, because Step 6.3's challenge pass will demand this step's output as evidence:

- Minimum protocol: read README / API surface / examples / config / hooks / CLI entrypoints.
- Output three columns per candidate: `stealable mechanism / graft point in the user's stack / reason rejected`.
- Closed-source or no public source → downgrade to API-level / architecture-concept assessment and say so (guessing at internals produces hallucinated steals).

Lesson: ocr's "the deterministic layer can't be stolen" flipped to "it's the easiest part to steal" only after the user pushed. The hunt is cheap; re-running the analysis after the user pushes is not. Done → Step 6.

### Step 6 — Verdict

1. **Finalize the draft** into one of five outcomes: adopt / trial / extract / watch-defer / landscape. watch-defer carries a revisit trigger (e.g. "ships a local CLI", "supports MCP", "stack develops X pain").
2. **Ambiguous zone definition (fail-closed)**: every rejection/landscape verdict that did not qualify at Step 0 is in the ambiguous zone. No self-classification out of it.
3. **Challenge pass** — runs on every ambiguous-zone rejection. Answer four fixed questions, plus one row "tool-specific axis" (may be "none, checked"):
   - Mechanism layer checked? (an idea-level rejection does not cover the implementation layer)
   - Alternative frame? (does Step 4's answer still hold now that the full picture exists)
   - Really nothing to steal? (point to Step 5's three-column output)
   - Cheaply testable — why untested? (discharge via the triage in 6.4)
   Any answer that flips → loop back to that step and redo from there.
4. **Testing triage + Gate Ledger**. Triage the "why untested" question into exactly one of:
   - `Runnable now` (install command exists + local input to run it on) → run it; paste output into the Gate Ledger. Install involved → a snapshot-before-install check first (its audit cost counts toward the budget; over budget → paper verdict allowed, marked "untested — audit cost"). After testing, the install is either removed or registered in trials/active.md — an unowned leftover install is how supply-chain debt accumulates.
   - `Runnable with user approval` → present the minimal test command + risk, wait.
   - `Not runnable cheaply` → name the blocking factor (paid account / interactive auth / missing data / hardware) + the exact command that would run if it were testable.
   A test that can't finish in-session → verdict marked `provisional` + executable test plan attached. A positive in-session result that needs a time dimension (frequency / retention / long-run cost) → upgrade to a trial verdict. Calibration: headroom's afternoon dry-run overturned a too-harsh paper sub-verdict; RTK's data-driven retirement is the trial-verdict analogue.
   Then emit the **Gate Ledger** block (see output-template) — Step 0 route + qualification, the four challenge answers one line each (checked → evidence pointer; unchecked → say so), triage outcome + test output. The ledger is what makes partial execution visible afterward; prose claims without artifacts don't survive an audit, and that is the point.
5. **Symmetric evidence obligations** — the adoption-first posture must not become an over-recommendation machine, so action verdicts carry their own paperwork:
   - rejection (ambiguous zone): show the work — frames tried, test output, extraction three-columns — plus "what evidence would overturn this".
   - trial: KPI + review date + kill condition + register the H2 entry in `~/Desktop/projects/.claude/trials/active.md` (`## <name> (YYYY-MM-DD)`) yourself；新 entry 只在 H2 下留 `started`／`status`／`detail` 三個索引欄位，長段寫 `trials/active/<slug>-<started>.md`，detail 缺失就停並回報 — 未登記的 trial 沒有 review reminder。
   - extract: named file/mechanism + graft point + next action. "Worth stealing" with no landing site is not an extract verdict.
6. **Action exit + ledger write-back** (both are steps, not afterthoughts):
   - Close with "the cheapest path to value" or "the test that would settle it". "None — overturn condition: X" is a legal value; Step 0 fast-kills skip the action path entirely (padding an honest kill makes the tool look more useful than the arithmetic says).
   - Write the verdict back to the precedent log in frame-scoped format. This skill **auto-writes** — a deliberate exception to the ask-first memory convention, because the graphify ledger sat stale for 7 weeks under ask-first and misled a later session. One guard: if this run is a bench / probe / simulation (the prompt supplied fabricated inventory facts, or says "測試環境"), skip the write-back and state that — a synthetic verdict in the real ledger is a fabricated precedent that later sessions will cite. trial/extract entries get `pending-outcome` + a pointer to their follow-up ledger. Re-evaluating a tool under a new frame requires a stated delta (what changed on the tool side or the stack side); 3 frame-scoped rejections + zero residuals → mark the tool `exhausted` (soft seal — new delta evidence reopens). Keep rows short; details go to a `[[reference_*]]` file. Full format rules: memory 帳本記錄格式 section (SSOT).

Verdict 定案、write-back 落帳後，完成後接 Self-Verify：Done → Step 7. 不要跳過 Step 7 直接把報告呈給使用者。

### Step 7 — Self-Verify（mandatory — 報告寫完後、呈給使用者前）

報告按 Output contract 草擬完成後，**必須**派一個 verify subagent 檢查報告是否遵守本 skill 的規矩，才進 Step 8。不可跳過、不可用「這次是 fast-kill 短版」為由省略（短版一樣驗，R4 有短版例外條款）。

Dispatch 規格：

- 報告草稿先落到唯讀快照檔（session scratchpad 或持久證據副檔，`chmod 444 <path>`）並以 `wc -l < <path>` 取得實際總行數 `{lines}`；草稿同時包含聊天主報告與完整證據副檔內容（預設路徑與退役／缺口盤點路徑皆然）
- `Agent` tool、`subagent_type: skill-verify-auditor`（sonnet+low、tools 僅 Read，定義檔釘死）
- description 固定含 marker 字串 `skill-verify:check-my-stack`（採用率統計 grep 用，不要改字）
- prompt 開頭固定放 `AUDIT_INPUT_MODE: FILE_SNAPSHOT`、`SNAPSHOT_PATH: {path}`、`SNAPSHOT_TOTAL_LINES: {lines}` 三行標頭，再接下方 template 全文（`skill-verify-auditor` 定義檔規定未帶這三行時不啟用讀檔模式、直接拒讀並全判 FAIL）

Verify prompt template（原文嵌入、`{path}` 換成報告草稿絕對路徑、`{lines}` 換成該檔實際總行數正整數）：

```
AUDIT_INPUT_MODE: FILE_SNAPSHOT
SNAPSHOT_PATH: {path}
SNAPSHOT_TOTAL_LINES: {lines}

你是 adversarial 合規審查員。用 Read 從第 1 行讀到第 {lines} 行讀取 SNAPSHOT_PATH，檢查這份競合分析報告是否遵守 check-my-stack skill 的規矩。偏置是「找違規」：無法確認有遵守就判 FAIL，不要善意推定。輸出第一行固定回報 `READ_RANGE: 1-{lines} / {lines}`，接著輸出 R1–R5 與最後一行 VERDICT。

逐條檢查（每條回 PASS / FAIL / EVIDENCE-UNAVAILABLE + 一句證據引述）：

R1【對帳有真的跑】load-bearing 列（被 Block 2 或 verdict 引為分母的列）的 Reconciled 標記是否引用了真實 probe 輸出（scripts/reconcile.sh 結果 / session jsonl invoke counts / hook log / launchd last-run）而非只填標籤？且報告若引用 precedent，是否標了三態之一（holds / partially stale / stale）？明寫 "no prior precedent retrieved" 視同有落。任一缺 = FAIL。

From GGGODLIN/gggodlin-cc-harness, MIT.

More from GGGODLIN/gggodlin-cc-harness