# Logic-Lens — Developer Guide (Claude Code)

This file contains instructions for Claude when working on the Logic-Lens repository itself.

## Project Layout

```
logic-lens/
├── skills/
│   ├── _shared/
│   │   ├── common.md              ← Language rule, Iron Law, Logic Score, yaml schema
│   │   ├── logic-risks.md         ← L1–L9 risk taxonomy definitions
│   │   ├── semiformal-guide.md    ← Execution tracing methodology + min thresholds
│   │   ├── semiformal-checklist.md ← Premises Construction Checklist (single source)
│   │   └── report-template.md     ← Report Template (English + Chinese, single source)
│   ├── logic-{review,explain,diff,locate,health}/
│   │   ├── SKILL.md               ← Frontmatter + process skeleton (triggers the skill)
│   │   └── *-guide.md             ← Detailed step-by-step instructions (loaded on demand)
│   └── logic-fix-all/             ← Skill 6: orchestrates the other five into one pipeline
│       ├── SKILL.md
│       ├── logic-fix-all-guide.md ← Navigation + shared context
│       ├── guide-phases-0-2-consent-scope-health.md
│       ├── guide-phases-3-5-review-locate-clarify.md
│       └── guide-phases-6-9-fix-iterate-report.md
├── .claude-plugin/                ← Claude Code plugin metadata
├── .codex-plugin/                 ← Codex CLI plugin metadata
├── gemini-extension.json          ← Gemini CLI extension metadata
├── commands/                      ← Short command wrappers installed by session-start hook
├── hooks/
│   ├── hooks.json                 ← Claude Code hook registration (uses ${CLAUDE_PLUGIN_ROOT} — portable across platforms)
│   └── session-start              ← Copies commands/ to ~/.claude/commands/ on session start
├── evals/content/v2/evals-v2.json  ← Content benchmark test cases (current)
├── evals/trigger/v2/               ← Trigger benchmark suites (per skill) — see Gotchas before relying on scores
├── evals/v1/                      ← Legacy v1 cases (archived for reference)
├── benchmarks/
│   ├── index.json                  ← Catalog of published runs
│   ├── reports/                    ← Human-readable markdown reports per version tag
│   └── runs/                       ← Frozen run summaries (workflow: see `benchmarks/README.md`)
├── scripts/                       ← Shell scripts invoked by `npm run ...` (validate, trigger-evals, content-evals, grader)
├── tests/                         ← Python unit tests (currently `test_grader.py` for the eval grader)
├── docs/                          ← Auxiliary docs (model compatibility, case studies, marketing assets)
├── skills-workspace/              ← Scratch space for in-progress skill iterations and benchmark probes
├── CONTRIBUTING.md                ← Contribution ground rules and versioning policy
└── AGENTS.md / GEMINI.md          ← Companion guides for Codex and Gemini CLI users
```

## Conventions

### SKILL.md Structure
- YAML frontmatter: `name` and `description` are required.
- `description` must include a "Do NOT trigger for:" clause.
- `description` should be explicit about trigger phrases — err on the side of triggering.
- Process section: 5–7 numbered items; each item cites a step in the guide file.
- Setup section: follow lazy loading from `skills/_shared/common.md` §13. Read only the relevant `common.md` sections and the active guide step upfront; load `logic-risks.md`, `semiformal-guide.md`, `semiformal-checklist.md`, `report-template.md`, and later guide sections on demand. Document any required eager read explicitly.

### Guide Files
- Numbered steps (Step 1, Step 2, ...).
- Each step explains the *why*, not just the *what*.
- Sub-steps use letters (Step 2a, 2b).
- Concrete examples preferred over abstract descriptions.

### Risk Codes
- Built-in: L1–L9 (defined in `skills/_shared/logic-risks.md`)
- Custom project-specific: C1, C2, ... (defined in `.logic-lens.yaml` at the repo root — optional file, omit if no custom codes needed)
- Every finding must be tagged with a risk code.

`.logic-lens.yaml` schema: see `skills/_shared/common.md` — `custom_risks` is a list of records with `code`, `name`, `description`, and `severity` fields.

### Version Sync
`package.json` is the source of truth for the version number. When bumping version, update:
1. `package.json` → `version`
2. `.claude-plugin/plugin.json` → `version`
3. `.claude-plugin/marketplace.json` → `version`
4. `.codex-plugin/plugin.json` → `version`
5. `gemini-extension.json` → `version`
6. `README.md` → version badge

### Iron Law
See `skills/_shared/common.md` — Iron Law section. That is the canonical definition; do not duplicate or paraphrase it here.

## Companion Docs by AI Tool

| File | Read by | Purpose |
|------|---------|---------|
| `AGENTS.md` | OpenAI Codex / Agents SDK | Task instructions for agent-based runners |
| `GEMINI.md` | Gemini CLI | Extension setup and skill invocation for Gemini |
| `CONTRIBUTING.md` | Human contributors | Ground rules, versioning policy, PR requirements |

## Development Commands

Logic-Lens has no runtime npm dependencies; `package.json` only declares script entry points. `npm install` is unnecessary for the four commands below.

```bash
npm run validate       # Validate repo structure and metadata consistency (scripts/validate-repo.sh)
npm run unit-tests     # Run Python unit tests under tests/ (currently grader tests)
npm run trigger-evals  # Run trigger-eval suites under evals/trigger/v2/ (scripts/run-trigger-evals.sh)
npm run content-evals  # Run evals/content/v2/evals-v2.json end-to-end through claude -p + grade (scripts/run-content-evals.sh) — costs API tokens
```

### 单次迭代评分（不跑完整套件）

```bash
python scripts/grade-iteration.py <iteration-dir>
# 对 skills-workspace/ 下某次迭代打分，无需触发完整 content-evals
# 详见 scripts/README.md 获取参数说明
```

Manual one-liners that don't require the scripts:

```bash
# Verify SKILL.md frontmatter exists in all six skills
grep -l "^name:" skills/*/SKILL.md

# Verify all guide files are present
ls skills/*/logic-*-guide.md

# Verify version is consistent across all metadata files (5 JSON files + README badge)
grep '"version"' package.json .claude-plugin/plugin.json .claude-plugin/marketplace.json .codex-plugin/plugin.json gemini-extension.json
grep -E 'version-[0-9]' README.md
```

## Gotchas

- **`npm run trigger-evals` recall is always 0% for Logic-Lens.** The suite delegates to skill-creator's `run_loop.py`, which asks a model (`claude -p`) whether a query *should* trigger a skill — but Logic-Lens skills are dispatched by Claude Code's IDE plugin mechanism, not by model decision, so every positive case scores 0. The suite is still useful for catching `description` regressions on negative (near-miss) cases; verify real triggers by hand in an interactive Claude Code session. (详细参数说明见 `scripts/README.md`)
- **`skills-workspace/` 目录结构约定：** 每次迭代建子目录（如 `iteration-a25b6c7/`），完成后在目录内放 `FINAL-REPORT.md`。草稿文件不要散放在根级别。根目录下现有少量历史遗留文件（`COMPARISON.md`、`FINAL-REPORT.md` 等）仅供参考，新工作请严格使用子目录。

## First Clone Setup

`hooks/hooks.json` uses the `${CLAUDE_PLUGIN_ROOT}` placeholder, so no path edit is needed regardless of where the repo lives.

**1. Run the session-start hook once manually** to install short-form command wrappers (the hook fires automatically on every session start once Claude Code picks the plugin up, but the first install needs a one-shot kick):

```bash
# Run from the repo root (macOS / Linux / WSL / Git Bash on Windows):
bash hooks/session-start
```

**2. Verify commands are installed:**

```bash
ls ~/.claude/commands/logic-*.md
# Expected: logic-diff.md  logic-explain.md  logic-fix-all.md  logic-health.md  logic-locate.md  logic-review.md
```

**Platform note:** the hook requires `bash`. On macOS and Linux it is preinstalled. On Windows, Claude Code itself runs under WSL or Git Bash, both of which provide `bash` — no extra install needed. For users installing through the marketplace (`/plugin install`), Claude Code auto-discovers `hooks/hooks.json` and runs the hook on every session — this manual step is only for clone-based development of the plugin itself.

## Adding a New Skill
1. Create `skills/logic-newskill/SKILL.md` following the existing SKILL.md pattern.
2. Create `skills/logic-newskill/logic-newskill-guide.md`.
3. Add a command wrapper to `commands/logic-newskill.md`.
4. No change needed in `gemini-extension.json` — Gemini CLI discovers skills from the `skills/` directory automatically.
5. No change needed in `.codex-plugin/plugin.json` — it points at `skills/` directory and auto-discovers subfolders.
6. Add the skill name to the `for skill in ...` loop in `hooks/session-start`:
   ```bash
   grep -n "for skill in" hooks/session-start
   ```
7. Add 3–5 eval cases to `evals/content/v2/evals-v2.json`. Optionally add trigger cases to `evals/trigger/v2/trigger-evals-{skill}.json` — but see Gotchas: positive trigger cases always score 0% for Logic-Lens; trigger evals are only useful for catching `description` regressions on negative cases.

## 하네스: Logic-Lens Skill Iteration

**目标:** 把"改 SKILL.md → 同步缓存 → 跑 eval → 诊断 → 验证净收益"的迭代闭环固化为可复用的 agent 团队，避免每次手动踩坑（尤其缓存同步）。

**触发:** 想**提升某个 logic-* skill 的 eval 分数 / 修复失败的 eval 模式**时，使用 `iterate-skill` 编排技能（它会按需调度 `eval-failure-analyzer` / `skill-editor` / `iteration-guard` 三个 agent 与 `sync-skill-cache` / `run-iteration-eval` 两个支撑技能）。单次提问、发版（用 `bump-version`）、新建 skill（用 `new-skill`）不触发本闭环。改完任何 `skills/**` 后跑 eval 前，**必须**先经 `sync-skill-cache` 同步缓存。

**变更 이력:**
| 날짜 | 변경 내용 | 대상 | 사유 |
|------|----------|------|------|
| 2026-06-01 | 初始构成：迭代闭环 harness（编排技能 iterate-skill + skill-editor/iteration-guard 两个新 agent + sync-skill-cache/run-iteration-eval 两个支撑技能；复用已有 eval-failure-analyzer/bump-version/new-skill） | 全体 | 把 skill 迭代主线工作固化为 agent 团队 |