---
name: seshat
description: Use Seshat MCP tools BEFORE writing or modifying any code. Triggers on: implementing features, fixing bugs, refactoring, modifying functions, creating files, editing files, choosing patterns, adding dependencies, building components, making any change to the codebase.
---
# Seshat — Project Convention Intelligence
Seshat maintains a knowledge graph of this project's conventions, patterns,
and architectural decisions. Use it BEFORE writing code — it tells you how
this codebase works and validates your approach against established rules.
## Workflow
**1. Session start**
```
query_project_context()
```
Understand the stack, languages, modules, and top conventions.
Runs automatically via MCP on first connection.
**2. Before writing any new symbol (function / class / module / type / constant)**
```
query_code_pattern(query="<name or concept>")
```
Finds existing implementations with that name or similar intent.
Examples:
- `query_code_pattern(query="parse_config")` — before writing a config parser
- `query_code_pattern(query="retry")` — before writing retry logic
- `query_code_pattern(query="UserRepository")` — before writing a data access class
When you know the kind you're after, pass `kind=` (`"function"` / `"type"` /
`"export"`) to cut noise — e.g. `query_code_pattern(query="Config", kind="type")`
returns the `Config` type, not functions/exports that merely share the name.
**3. Before choosing any pattern**
```
query_convention(topic="<area>")
```
Returns adopted patterns with confidence score and trend (rising/stable/declining).
Examples:
- `query_convention(topic="error handling")` — which error types, how propagated
- `query_convention(topic="logging")` — which logger, log levels, format
- `query_convention(topic="naming")` — camelCase, snake_case, PascalCase, file naming
- `query_convention(topic="testing")` — test framework, fixture style, assertion patterns
**4. Before writing (validate your plan)**
```
validate_approach(description="<what you plan to do>")
```
Returns the project knowledge relevant to your plan: `relevant_rules`,
`conventions`, `decisions`, `observations`, `contradictions`, `duplicates`,
and a neutral count `summary`. This is deterministic keyword retrieval, **not**
a verdict — it cannot see the code you will write.
What to do with the result:
1. Read each relevant rule and convention.
2. Decide whether it applies to what you're about to write.
3. Bring your plan into line with the ones that do.
4. Need more — `query_convention(topic)` for full examples, `query_code_pattern`
for a duplicate, `query_dependencies` for blast radius.
5. If a rule is stale or you disagree with a recorded decision, `update_decision`
/ `remove_decision` so future sessions inherit the correction.
If the `summary` says nothing was found, proceed using your own judgment.
Examples:
- `validate_approach(description="add axios for HTTP calls")`
- `validate_approach(description="create a singleton DatabaseManager class")`
- `validate_approach(description="use console.log for debug output")`
Pass `file_context="<file you'll edit>"` to have any duplicate matches enriched
with blast radius (how many files depend on them) — so you see the cost of
touching a duplicate before you do.
**5. Before editing an existing file**
```
query_dependencies(path="<relative/file/path>")
```
Returns: direct dependencies, dependents, blast_radius (low/medium/high).
High blast radius = many things depend on this file, edit carefully.
**6. After discovering a new pattern not yet in the knowledge base**
```
record_decision(
description="<pattern>", reason="<why>", category="<area>",
examples=[{file:"<path>", line:<n>, end_line:<n>, snippet:"<code>"}],
)
```
**Anchor every code-related decision to real code.** Pass `examples` with a
`snippet` (file + line range + the code) so future sessions see *where* and
*how* the pattern looks, not just prose. If you can't assemble a snippet, at
least pass `file_path="<path>"` — Seshat then auto-anchors the decision to the
matching symbol in that file. Omit both only for genuinely codeless decisions
(e.g. a pure team/style agreement not tied to any code).
Persists the decision for future sessions — survives re-scans and context resets.
- `update_decision(id=<id>, description="<updated>")` — when a decision evolves
- `remove_decision(id=<id>, reason="<why>")` — when superseded; soft-deleted with audit trail
**7. Before committing or during code review**
```
map_diff_impact()
```
Maps uncommitted git changes to affected symbols, dependents, blast radius,
and convention risks in a single call. Helps assess the impact of your changes
before committing or raising a PR.
Returns:
- `changed_files` — list of changed files with status (modified/added/deleted/untracked/conflicted)
- `affected_symbols` — exports, public functions, and types touched, each with `dependent_count`, `dependents [{file, line}]`, and `blast_radius` (low/medium/high)
- `convention_risks` — conventions whose evidence files are being modified, with `topic`, `weight`, `adoption`, `is_golden_file`, and a human-readable `note`
- `blast_radius_summary` — aggregate `total_dependents`, `total_affected_symbols`, `total_changed_files`, `risk` (none/low/medium/high)
- `metadata.next_steps` — ranked, actionable suggestions
Parameters (all optional):
- `staged_only=true` — analyse only staged changes (`git diff --cached`); mutually exclusive with `base`
- `base="<ref>"` — compare against a branch, tag, or commit instead of HEAD (e.g. `"main"`, `"v1.2.3"`, `"origin/main"`)
- `repo_path="<path>"` — override the git root; defaults to the project root the server was started in; only needed for submodule analysis
Examples:
```
map_diff_impact() — all uncommitted changes vs HEAD
map_diff_impact(staged_only=true) — staged changes only (pre-commit check)
map_diff_impact(base="main") — everything on this branch vs main
map_diff_impact(base="origin/main") — compare against remote main
map_diff_impact(repo_path="vendor/libfoo") — analyse a submodule
```
## All 9 Tools
| `query_project_context` | Session start — stack, modules, top conventions |
| `query_convention` | Before choosing any pattern — error handling, naming, logging, etc. |
| `query_code_pattern` | Before writing any new symbol — find existing implementations |
| `query_dependencies` | Before editing a file — understand blast radius |
| `validate_approach` | Before writing — verify plan against rules and conventions |
| `record_decision` | After discovering a pattern — persist institutional knowledge |
| `update_decision` | When a decision evolves — update reasoning or classification |
| `remove_decision` | When a decision is superseded — soft-delete with reason |
| `map_diff_impact` | Before committing or code review — assess change impact |
## Do NOT use Seshat for:
- Reading file contents (use file reading tools)
- Searching for string literals or config values (use text search)
- Running tests, builds, or compiling the project