scip-cli / rules
Cursor rule4 starsChanged 20 days agoMITView on GitHub
scip-cli dev workflow and TDD with the shared fixture
- Installs packages
Where files are headingNew Cursor rule files have more rules about planning and tracking tasks, and fewer about code style.
Of the Cursor rule files we read, the 4,329 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- new-commandSkill
- sql-benchSkill
- testSkill
- scip-cliSkill
The file
We split this agent.mdc into the rules it gives an agent
10 rules. About 0 are common, 5 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
After publishing: pip install scip-cli → smoke-test → pip install -e ".[dev]" to restore local.
- Very specific: line 43
Use
scripts/test.sh: before committing to catch all issues (lint, format, types, tests). - Distinctive: line 68
Do not spawn broad code-review agents until this pass is done (or explain why skipped).
- Distinctive: line 72
When you or a review subagent finds a repo issue — bug, dead code, cycle, risky hub, stale type, unused import — stop and ask first:
- Very specific: line 76
If yes (the signal is in documents, mentions, global_symbols, defn_enclosing_ranges):
- Distinctive: line 83
Only skip step 1 when the issue is outside the index (runtime, CLI UX, docs drift, git, env, concurrency, test harness).
- Very specific: line 101
Add new rows to dogfood.md when you find another gap.
- Distinctive: line 183
When dogfooding another repo surfaces a bug or false positive (analyze noise, dead-export mistake, cycle, stale type, refs mismatch):
- Distinctive: line 198
If both layers help during development, keep both until e2e passes, then delete duplicate in-memory repros — fixture is the source of truth.
- Very specific: line 216
After flag changes: update SKILL + README command list.
≈ “Common” is an estimate: at least 1 in 5 of the 6,873 Cursor rule files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
---
description: scip-cli dev workflow and TDD with the shared fixture
alwaysApply: true
---
# scip-cli agent
**Work from repo root.** CLI usage, flags, and user gotchas: `scip-cli skill` (source: `scip_cli/SKILL.md`). Read once per task — do not duplicate SKILL here.
**Cursor:** Skills in `.cursor/skills/` (`test`, `sql-bench`, `new-command`) — folder name = frontmatter `name:`; agent reads when relevant. Slash commands in `.cursor/commands/` only for workflows you invoke (`dogfood`, `migration-problems`, `release`); never pair the same workflow as both.
**Almost always:** bare `scip-cli` on PATH must be **this checkout live** (`pip install -e ".[dev]"`). All examples use `scip-cli` — never `.venv/bin/scip-cli`, `python -m scip_cli`, or other paths. Only swap to PyPI briefly to smoke-test a release.
## Bootstrap
From repo root — keep this mapping for the whole dev session:
```bash
pip install -e ".[dev]"
scip-cli --version # must match scip_cli/__init__.py
pre-commit install
scip-cli skill ~/.claude/skills/scip-cli/
```
After publishing: `pip install scip-cli` → smoke-test → `pip install -e ".[dev]"` to restore local.
Optional venv for isolation only: create/activate, then same `pip install -e ".[dev]"` — `scip-cli` still runs from PATH, not a venv-relative path.
Node.js + `npx` required for integration tests (`scip-typescript`). Optional: `SCIP_CLI_DEBUG=1` (SQL to stderr, truncated).
## Lint / test
|Task|Command|
|---|---|
|**All checks**|`scripts/test.sh` (lint + format + types + tests)|
|Full suite|`pytest`|
|E2e loop|`pytest tests/test_e2e.py tests/test_e2e_analyze_patterns.py`|
|Lint / format|`ruff check .` / `ruff format .`|
|Typecheck|`basedpyright --warnings scip_cli/ scripts/`|
Pre-commit, CI, and publish: `./scripts/test.sh` (same gate). No pre-push hook. E2e before commit on command changes.
**Use `scripts/test.sh`** before committing to catch all issues (lint, format, types, tests). This matches what pre-commit and CI run.
## Improving this repo (do this before review subagents)
**Dogfood on the repo itself** — faster and more honest than spawning reviewers:
```bash
scip-cli reindex
scip-cli analyze --limit 25
scip-cli analyze --priority high --limit 25 # dead code & cycles only
scip-cli analyze scip_cli --limit 15 # directory
scip-cli analyze scip_cli/queries.py --limit 20 # file (+ scoped project)
```
Interpretation: README § *Finding easy wins with analyze*. Target = omit (project), directory, file, or symbol — not `--path` for scope.
|Priority|Section|Action|
|---|---|---|
|1|**Cycles**|Break production file dependency cycles (`cache`↔`scope` was one)|
|2|**Unreferenced / dead exports**|No ref usage / no external refs — verify with `rg`, delete or `_` prefix|
|3|**Same-file only**|Module-private by usage — rename to `_`|
|4|**Stale types**|Low-consumer classes — merge or justify|
`analyze` skips test paths by default (`tests/`, `*.test.*`, `*.spec.*`); `--include-tests` to include. Reindex after large edits.
Do **not** spawn broad code-review agents until this pass is done (or explain why skipped).
## Analyze feedback loop (mandatory)
When you or a review subagent finds a repo issue — bug, dead code, cycle, risky hub, stale type, unused import — **stop and ask first:**
> *Could our SQLite index have predicted this, and `analyze` just doesn't surface it yet?*
If **yes** (the signal is in `documents`, `mentions`, `global_symbols`, `defn_enclosing_ranges`):
1. **Red on the fixture** — minimal generic repro + e2e test (see **TDD → External project feedback**). Do not name real customer repos in tests.
2. **Extend `analyze`** — new or tuned SQL/heuristic in `scip_cli/analyze/`, priority in `sections.py`; unit tests only for graph/SQL plumbing (`analyze_db.py`, `test_analyze_graph.py`).
3. **Dogfood** — `reindex` on this repo (or re-run fixture e2e) → confirm signal appears or false positive is filtered.
4. **Then** fix production code in the other repo (or document a known blind spot).
Only skip step 1 when the issue is **outside the index** (runtime, CLI UX, docs drift, git, env, concurrency, test harness).
### Retrospective: caught manually, SQLite already had it
|Issue we hit|Index signal|Analyze today|Gap / next check|
|---|---|---|---|
|`cache` ↔ `scope` import cycle|cross-file `mentions` edges|`[high] Cycles`|**Caught** — keep dogfooding cycles|
|Cross-file dead export (`get_refs_for_symbols`)|def with no external `mentions`|`[high] Dead exports`|**Caught**|
|Same-file-only dead code|def, `role=0` only in def file|`[high] Unreferenced` or `[medium] Same-file only`|**Caught** (since extended)|
|Same-file helper without `_` (`run_with_fallback`)|same-file `role=0` or none|`[medium] Same-file only` / unreferenced|**Caught** — rename to `_`|
|Typing-only dataclasses (`ProjectSettings`, `IndexScope`)|type `#` symbol, 0 consumer files|`[high] Stale types` + `stale_type_noise`|**Filtered** — index can't see annotations; document or optional `--types`|
|`analyze/*` section runners “dead”|no external refs|noise filter in `common.py`|**Filtered** — framework pattern|
|Unused import|`role=2` mention, no in-file use|`[high] Unused imports` (per file)|**Caught** on file target|
|Hub before editing (`resolve_symbol`, `queries.py`)|fan-in / consumer count|`[medium] Change surface` / `[low] Hotspots`|**Caught** on file target; project hubs are low tier|
|Symbol only used from tests|consumers all under `tests/`|`[low] Test-only consumers`|**Partial** — Python index often omits same-file `role=0`; verify with `rg`|
|Indexer omits same-file Python calls|no `role=0` for in-module use|unreferenced / test-only false positives|**Index gap** — not fixable in SQL alone; demoted test-only to low|
|Duplicate / parallel helpers|—|—|**Not in index** — `rg`, not analyze|
Add new rows to `dogfood.md` when you find another gap; implement the SQL check before the next manual review pass.
### Size / complexity checks (assessed — don’t promote to high/medium)
SQLite has **line ranges** (`defn_enclosing_ranges`) so LOC is cheap. That does **not** mean “big function” belongs next to dead exports.
|Idea|In index?|Verdict|
|---|---|---|
|**LOC ≥ N** alone|Yes|**LOW at best** — noisy (`main`, argparse, legitimate parsers). Not a nuke candidate.|
|**LOC + fan-in** (large hub)|Yes|**Already covered** by `[low] Bottlenecks` (fan-in × fan-out). Add `loc=` to that output if helpful; don’t duplicate as medium.|
|**LOC + consumers** on file target|Yes|**Change surface** (medium) already sorts by consumers with line ranges — drill there.|
|**Symbol pressure**|Yes|**Per-symbol** `analyze Foo` shows `loc × fan_in × fan_out`.|
|**God class / many members**|Yes|Use `members Class` — not analyze.|
|**File byte size / cyclomatic complexity**|No|Out of scope for SCIP index.|
|**Fat file (many symbols)**|Yes|Low value; coupling/hotspots approximate module heat.|
**Rule:** size-only checks stay **low or file-drill-down**; never high/medium unless paired with a **structural smell** (cycle, dead export, zero production consumers). Prefer enriching existing low-tier lines (e.g. show `loc` on bottlenecks) over a new dashboard section.
## SQL / analyze benchmarks
The e2e fixture and this repo's own index are **small** — every query looks fast here. That hides blowups on real projects (40MB+ indexes, dense graphs).
### Scaled :memory: benchmark (primary)
`tests/bench_db.py` generates a deterministic 1000-file / ~15K-symbol / ~100K-mention DB in `:memory:`. `tests/test_bench_queries.py` times all key queries on it.
**Before/after comparison flow:**
```bash
# 1. Before changes — save baseline
scripts/bench.sh --baseline
# 2. Make your SQL/query changes
# 3. Compare — runs current, diffs against baseline
scripts/bench.sh --compare
# Or just run current without comparison
scripts/bench.sh
```
Output per query: `BENCH:<name>:<elapsed_ms>`. The compare table shows ratio (>1.0 = regression, <1.0 = improvement).
**When to use:** Any change to `queries.py`, `analyze/*`, `symbols.py` SQL clauses, or `sql.py` pragmas. Run `scripts/bench.sh --compare` before committing.
### Large cached index benchmark (secondary)
For queries that behave differently on real 40MB+ indexes vs the synthetic DB:
```bash
python3 -u -c "
import sqlite3, time, sys
from pathlib import Path
sys.path.insert(0, '.')
from scip_cli.analyze import project as p
from scip_cli.sql import configure_read_connection
db_path = Path.home() / '.cache/scip-cli/projects/<project-slug>/index.db'
db = sqlite3.connect(f'file:{db_path}?mode=ro', uri=True)
configure_read_connection(db)
for name, fn in [('hotspots', p.hotspots), ('cycles', p.cycles), ('dead_exports', p.dead_exports)]:
t = time.perf_counter(); fn(db, limit=25); print(f'{name}: {(time.perf_counter()-t)*1000:.0f}ms')
"
```
**In CI:** `tests/test_e2e_perf.py` (whole commands) and `tests/test_analyze_perf.py` (per-check on mini DB) catch gross regressions on the tiny fixture only — they **will not** catch large-repo OOMs. Use `scripts/bench.sh --compare` for that.
## TDD
### Default: extend the shared fixture
**One indexed TS project** — `tests/fixtures/typescript-project/` — indexed once per session via `indexed_fixture` (`conftest.py`). Stable names live in `tests/fixture_catalog.py`.
1. **Red** — add a **minimal** `.ts` file (or tweak an existing one) that reproduces the SCIP shape; assert in `tests/test_e2e.py` or `tests/test_e2e_analyze_patterns.py` using `cli` / `open_index_db` + analyze helpers.
2. **Green** — fix `scip_cli/` (commands, `analyze/*`, `queries.py`, …).
3. **Refactor** — only if a pure helper deserves isolation.
- **E2e** (`cli` / `indexed_fixture`): in-process `main()` or direct Python API on the **real** index — default for behavior.
- **No subprocess** for CLI tests; no `reindex` in e2e (mutates `~/.cache/scip-cli`).
- New symbols/paths: fixture file + `fixture_catalog.py` constant — never hardcode paths in test bodies.
### External project feedback → fixture (mandatory workflow)
When dogfooding **another repo** surfaces a bug or false positive (analyze noise, dead-export mistake, cycle, stale type, refs mismatch):
1. **Capture the pattern, not the project** — note the SCIP shape (module `/`, export alias `foo0:`, lazy import, `Props#`, barrel cycle, …). Do **not** copy real repo names, paths, or filenames into tests or docs.
2. **Red on the fixture** — smallest TS repro under `tests/fixtures/typescript-project/` with generic names (`LazyPanel`, `evictItem`, `OrphanWidget`, …). E2e test proves the bug against **real `scip-typescript`** output.
3. **Green** — fix analyze heuristics / SQL / CLI; dogfood on this repo if applicable.
4. **Verify** — `pytest tests/test_e2e_analyze_patterns.py` (or full `pytest`); only then trim redundant tests.
**Prefer fixture e2e over fake SQLite graphs.** `tests/analyze_db.py` (`AnalyzeDbBuilder`, `:memory:`) is for SQL/dashboard **plumbing** and graph primitives (`test_analyze_graph.py`, `mini_codebase_db`) — not for reproducing production SCIP symbol shapes. Hand-built symbols often diverge from scip-typescript (path format, `0:` aliases, module rows) and can pass while production still breaks.
|Use fixture e2e|Use `analyze_db` unit|
|---|---|
|False positives / analyze checks from real projects|Tarjan, edge-type SQL, `run_all` section wiring|
|Any behavior that depends on indexer symbol strings|Noise filters with one or two synthetic rows|
|CLI commands (`refs`, `search`, `analyze` output)|Merge/index prune tests|
If both layers help during development, **keep both until e2e passes**, then delete duplicate in-memory repros — fixture is the source of truth.
## Codebase map (contributors)
|Area|Path|Notes|
|---|---|---|
|Commands|`scip_cli/commands/`|Thin; SQL in `queries.py` / `analyze/`|
|Index build|`scip_cli/indexing.py`|`index.db.next` → promote; flock; `>10` tsconfigs log progress|
|Variable prune|postprocess + `merge.py`|Omit const/let/var on **COPY**, not DELETE — no `variable` kind|
|Session|`scip_cli/session.py`|`setup()`, `resolve_one_symbol` (limit 2 for ambiguity)|
|Analyze filters|`scip_cli/analyze/common.py`|`is_test_path`, `analyze_noise` (`_` helpers)|
`todo.md` = tracked work; `dogfood.md` = future ideas only. Wishlist/backlog in `docs/` per workspace rules.
## Docs touch points
- User install + analyze guide → `README.md`
- Agent/user CLI reference → `scip_cli/SKILL.md` (must match `__main__.py` flags)
- After flag changes: update SKILL + README command list; run `scip-cli skill` to verify output
## Dogfood Notes
Future improvements from using the CLI on real projects.
### Workflow
Requires bare `scip-cli` mapped to local (`pip install -e ".[dev]"` from repo root).
```bash
scip-cli reindex
scip-cli analyze --limit 25
scip-cli analyze scip_cli/queries.py --limit 20 # drill into hubs
```
Project-wide analyze skips test paths by default; `--include-tests` to include. See README **Finding easy wins with analyze**.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

