context-mode

Files (5)

• SKILL.md
• anti-patterns.md · references/
• patterns-javascript.md · references/
• patterns-python.md · references/
• patterns-shell.md · references/

SKILL.md (first lines)

# Context Mode: Default for Large Output

## MANDATORY RULE

<context_mode_logic>
<mandatory_rule>
Use context-mode for commands, files, tool outputs, API calls, logs, tests, builds, or datasets that may produce large output or need server-side analysis. Do not use it as a blanket replacement for normal Pi tools or bounded shell execution.
</mandatory_rule>
</context_mode_logic>

Use normal Pi tools for:

- exact small file reads before editing;
- exact edits and writes;
- symbol and module tools, AST tools, and LSP tools for code intelligence;
- small grep/find/ls lookups where direct output is already bounded.

Use Bash directly only for bounded commands that genuinely need shell execution, such as tests/builds/package commands, read-only git inspection, cloud/database CLIs with narrow filters, and small purpose-built scripts. Root prompt policy still controls destructive shell commands, mutating git, sudo, secret paths, and user approval requirements.

Use `ctx_execute`, `ctx_execute_file`, indexing, or search for commands that read, query, fetch, list, log, test, build, diff, inspect, or call external services when their output may exceed the useful context budget or needs analysis before summarization.

When uncertain about output size, prefer context-mode. Every KB of unnecessary context reduces the quality and speed of the session.

## Decision Tree

```
About to run a command / read a file / call an API?
│
├── Need an exact small file read for editing or source inspection?
│   └── Use normal Pi read, symbol/module, AST, or LSP tools
│
├── Command genuinely needs shell execution and has bounded output?
│   └── Use Bash, subject to root prompt safety and git rules
│
├── Output MIGHT be large or you're UNSURE?
│   └── Use context-mode ctx_execute or ctx_execute_file
│
├── Fetching web documentation or HTML page?
│   └── Use ctx_fetch_and_index → ctx_search
│
├── Using Playwright (navigate, snapshot, console, network)?
│   └── ALWAYS use filename parameter to save to file, then:
│       browser_snapshot(filename) → ctx_index(path) or ctx_execute_file(path)
│       browser_console_messages(filename) → ctx_execute_file(path)
│       browser_network_requests(filename) → ctx_execute_file(path)
│       ⚠ browser_navigate returns a snapshot automatically — ignore it,
│         use browser_snapshot(filename) for any inspection.
│       ⚠ Playwright MCP uses a SINGLE browser instance — NOT parallel-safe.
│         For parallel browser ops, use agent-browser via execute instead.
│
├── Using agent-browser (parallel-safe browser automation)?
│   └── Run via execute (shell) — each call gets its own subprocess:
│       execute("agent-browser open example.com && agent-browser snapshot -i -c")
│       ✓ Supports sessions for isolated browser instances
│       ✓ Safe for parallel subagent execution
│       ✓ Lightweight accessibility tree with ref-based interaction
│
├── Processing output from another MCP tool (Context7, GitHub API, etc.)?
│   ├── Output already in context from a previous tool call?
│   │   └── Use it directly. Do NOT re-index with ctx_index(content: ...).
│   ├── Need to search the output multiple times?
│   │   └── Save to file via ctx_execute, then ctx_index(path) → ctx_search
│   └── One-shot extraction?
│       └── Save to file via ctx_execute, then ctx_execute_file(path)
│
└── Reading a file to analyze/summarize (not edit)?
    └── Use ctx_execute_file (file loads into FILE_CONTENT, not context)
```

## When to Use Each Tool

| Situation                                    | Tool                                                            | Example                                            |
| -------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------- |
| Hit an API endpoint                          | `ctx_execute`                                                   | `fetch('http://localhost:3000/api/orders')`        |
| Run CLI that returns sizable data            | `ctx_execute`                                                   | `gh pr list`, `aws s3 ls`, `kubectl get pods`      |
| Run tests with potentially large output      | `ctx_execute`                                                   | `npm test`, `pytest`, `go test ./...`              |
| Read-only git operations with sizable output | `ctx_execute`                                                   | `git log --oneline -50`, `git diff HEAD~5`         |
| Docker/K8s inspection                        | `ctx_execute`                                                   | `docker stats --no-stream`, `kubectl describe pod` |
| Read a log file                              | `ctx_execute_file`                                              | Parse access.log, error.log, build output          |
| Read a data file                             | `ctx_execute_file`                                              | Analyze CSV, JSON, YAML, XML                       |
| Read source code to analyze                  | `ctx_execute_file`                                              | Count functions, find patterns, extract metrics    |
| Fetch web docs                               | `ctx_fetch_and_index`                                           | Index React/Next.js/Zod docs, then search          |
| Playwright snapshot                          | `browser_snapshot(filename)` → `ctx_index(path)` → `ctx_search` | Save to file, index server-side, query             |
| Playwright snapshot (one-shot)               | `browser_snapshot(filename)` → `ctx_execute_file(path)`         | Save to file, extract in sandbox                   |
| Playwright console/network                   | `browser_*(filename)` → `ctx_execute_file(path)`                | Save to file, analyze in sandbox                   |
| MCP output (already in context)              | Use directly                                                    | Don't re-index — it's already loaded               |
| MCP output (need multi-query)                | `ctx_execute` to save → `ctx_index(path)` → `ctx_search`        | Save to file first, index server-side              |
| Wipe indexed KB content                      | `ctx_purge(confirm: true)`                                      | Permanently deletes all indexed content            |

## Automatic Triggers

Use context-mode for these when output may be large, needs filtering/summarization, or benefits from server-side analysis:

- **API debugging**: "hit this endpoint", "call the API", "check the response", "find the bug in the response"
- **Log analysis**: "check the logs", "what errors", "read access.log", "debug the 500s"
- **Test runs**: "run the tests", "check if tests pass", "test suite output"
- **Git history**: "show recent commits", "git log", "what changed", "diff between branches"
- **Data inspection**: "look at the CSV", "parse the JSON", "analyze the config"
- **Infrastructure**: "list containers", "check pods", "S3 buckets", "show running services"
- **Dependency audit**: "check dependencies", "outdated packages", "security audit"
- **Build output**: "build the project", "check for warnings", "compile errors"
- **Code metrics**: "count lines", "find TODOs", "function count", "analyze codebase"
- **Web docs lookup**: "look up the docs", "check the API reference", "find examples"

For bounded one-shot commands with small expected output, use the normal Pi tool or Bash path allowed by root policy instead.

## Language Selection

| Situation                 | Language     | Why                                   |
| ------------------------- | ------------ | ------------------------------------- |
| HTTP/API calls, JSON      | `javascript` | Native fetch, JSON.parse, async/await |
| Data analysis, CSV, stats | `python`     | csv, statistics, collections, re      |
| Shell commands with pipes | `shell`      | grep, awk, jq, native tools           |
| File pattern matching     | `shell`      | find, wc, sort, uniq                  |

## Search Query Strategy

- BM25 uses **OR semantics** — results matching more terms rank higher automatically
- Use 2-4 specific technical terms per query

From som1shi/pi-config, MIT.

More from som1shi/pi-config