using-grafel

Files (1)

• SKILL.md

SKILL.md (first lines)

# using-grafel

A practical routing guide for AI agents in a grafel-registered codebase.
grafel exposes **22 intent-named tools**. Each one collapses a family of
related operations under a single verb with a discriminator parameter
(`kind` / `direction` / `aspect` / `detail` / `action` / `scope`). Pick the
tool by **intent**, then pick the discriminator value for the specific
question.

The single biggest win: **stop reasoning over raw source by hand.** When the
question is "are these two things different?", "what's affected?", "what
calls this?", or "what flows through here?", there is a dedicated tool that
answers it structurally. Reaching for `grafel_get_source` + manual reading is
the slow, error-prone path.

---

## 1. Intent → tool map

### Comparison & analysis (reach here FIRST)

| Your intent | Tool + discriminator |
|---|---|
| Compare reference vs candidate response shape | `grafel_diff` `aspect=response_shape` — **not** `get_source` + eyeball |
| Compare request payloads between two refs | `grafel_diff` `aspect=payload` |
| Compare auth posture between two refs | `grafel_diff` `aspect=auth` |
| Compare constant/literal parity between two refs | `grafel_diff` `aspect=literals` |
| Compare arbitrary entity sets between two refs | `grafel_diff` `aspect=refs` |
| What's affected if I change X (one entity) | `grafel_impact_radius` `scope=entity` |
| What's affected by this changeset / PR | `grafel_impact_radius` `scope=changeset` |
| Tech-debt: dead code | `grafel_debt` `kind=dead_code` |
| Tech-debt: import/dependency cycles | `grafel_debt` `kind=cycles` |
| Tech-debt: stub / unimplemented functions | `grafel_debt` `kind=stubs` |
| Tech-debt: impure functions | `grafel_debt` `kind=impure` |
| License audit | `grafel_debt` `kind=license` |
| Security findings | `grafel_security` `kind=findings` |
| Hardcoded secrets | `grafel_security` `kind=secrets` |
| Auth coverage across endpoints | `grafel_security` `kind=auth_coverage` |
| Test coverage | `grafel_test_analysis` `kind=coverage` |
| Test reachability | `grafel_test_analysis` `kind=reachability` |
| Contract-test effectiveness | `grafel_test_analysis` `kind=contract_effectiveness` |
| Recurring code patterns | `grafel_patterns` `kind=code` |
| Recurring graph patterns | `grafel_patterns` `kind=graph` |
| Template patterns | `grafel_patterns` `kind=template` |

### Navigation & traversal

| Your intent | Tool + discriminator |
|---|---|
| What calls X | `grafel_related` `direction=callers` |
| What X calls | `grafel_related` `direction=callees` |
| Direct neighbours of X | `grafel_related` `direction=neighbors` |
| What X uses | `grafel_related` `direction=uses` |
| What uses X | `grafel_related` `direction=used_by` |
| Route(s) between two entities | `grafel_find_paths` |
| Graph slice around entity(s) | `grafel_subgraph` |
| Trace data flow | `grafel_trace` `kind=data` |
| Trace control flow | `grafel_trace` `kind=control` |
| Trace def-use | `grafel_trace` `kind=def_use` |
| Trace effects | `grafel_trace` `kind=effects` |

### Locate & read

| Your intent | Tool |
|---|---|
| Find entities by name/pattern/kind | `grafel_find` |
| Full detail on one entity | `grafel_inspect` |
| Raw source for an entity/range | `grafel_get_source` |

### HTTP surface

| Your intent | Tool + discriminator |
|---|---|
| List HTTP endpoints | `grafel_endpoints` `detail=list` |
| Endpoint contract (request/response shape) | `grafel_endpoints` `detail=contract` |
| Endpoint security posture | `grafel_endpoints` `detail=posture` |
| Cross-repo client→server HTTP joins | `grafel_cross_links` |

### Orientation

| Your intent | Tool + discriminator |
|---|---|
| Where am I / which group+repo | `grafel_orient` `view=me` |
| Codebase overview | `grafel_orient` `view=overview` |
| Module clusters | `grafel_orient` `view=clusters` |
| Topology | `grafel_orient` `view=topology` |
| Module breakdown | `grafel_orient` `view=modules` |
| Per-repo freshness / is it indexed | `grafel_index_status` |

### Findings & workflow

| Your intent | Tool + discriminator |
|---|---|
| List saved findings | `grafel_findings` `action=list` |
| Save a finding | `grafel_findings` `action=save` |
| Run docgen lifecycle | `grafel_docgen` `action=start·status·list·promote·abort·validate` |
| Apply doc semantics/repairs/enrichments | `grafel_docgen_apply` `kind=semantics·repairs·enrichments` |

### Meta

| Your intent | Tool + discriminator |
|---|---|
| Emit feedback telemetry | `grafel_event` `kind=feedback` |
| Emit persona telemetry | `grafel_event` `kind=persona` |
| Tool-call metrics | `grafel_mcp_metrics` |

---

## 2. Should I use grafel at all?

Use grafel when the answer requires **graph traversal or structural
comparison** — relationships, call chains, flows, impact, diffs, posture.
Reach for grep/Read when you need **text search** — find a literal string,
read one known file, check a config value.

**Skip grafel** when:
- The question is answered by reading a single known file (use `Read`).
- You only need a literal string or regex (`rg`).
- The repo has never been indexed (check `grafel_index_status`).

From cajasmota/grafel, MIT.

More from cajasmota/grafel