grafel-consult

Files (13)

• SKILL.md
• api-designer.md · personas/
• architect.md · personas/
• business-analyst.md · personas/
• compliance-officer.md · personas/
• data-engineer.md · personas/
• devops-reviewer.md · personas/
• dx-engineer.md · personas/
• performance-reviewer.md · personas/
• qa-reviewer.md · personas/
• refactor-critic.md · personas/
• security-auditor.md · personas/
• solutions-architect.md · personas/

SKILL.md (first lines)

# grafel-consult

Interactive consultant skill. The user **hires** one specialist persona at a time; that persona becomes the active consultant for the conversation and answers the user's questions using the grafel knowledge graph + generated tech docs as its primary navigation surface.

This is **not** an auto-fan-out skill. It does not run all 8 personas in batch. It does not produce a synthesis report. It does not auto-save findings. See `docs/architecture/personas.md` (v3) for the full paradigm and the reasoning behind the redesign.

## Hard and soft dependencies

| Dependency | Type | Why |
|---|---|---|
| `/grafel-resolve` | Hard | Orphan edges make impact-radius analysis meaningless |
| `/grafel-tech-docs` | Hard | Personas read module markdown to ground their answers |
| `/grafel-business-docs` | Soft | Business-analyst persona fidelity improves |
| `/grafel-security-audit` | Soft | Security-auditor persona can deduplicate against existing findings |

If tech docs are missing, the skill aborts:
> Tech docs not found at `~/.grafel/docs/<group>/`. Run `/grafel-tech-docs` first, then re-invoke `/grafel-consult`.

## CRITICAL TOOL DISCIPLINE

The active persona MUST use grafel MCP tools for ALL graph navigation. Pre-flight: call `grafel_orient (view=me)` first.

## When to use this skill

- "Get an architect's view of this codebase."
- "Hire a security auditor to look at our auth flow."
- "I want a business analyst's read on the order module."
- "What would a performance reviewer say about this endpoint?"
- "Review API design consistency."
- "Check test coverage on the billing module."
- `/grafel-consult` (slash command).

## Flags (optional)

- `--persona <name>` — hire a specific consultant directly without going through catalog selection (e.g. `--persona architect`).
- `--list` / `--catalog` — print the catalog and exit.
- `--release` — release the currently active consultant.
- `--switch <name>` — release the current consultant and hire `<name>`.
- `--resume <session-id>` — resume a specific saved session by ID (skips the session picker).
- `--new` — force a new session, skipping the active-session list.

## Shipped catalog

Twelve consultants ship as persona files in `skills/grafel-consult/personas/`. Users may add their own under `~/.claude/agents/grafel-<persona>.md`.

| Consultant | File | Lens |
|---|---|---|
| architect | `personas/architect.md` | Module layering, coupling, cyclic deps, god modules, ADR opportunities |
| security-auditor | `personas/security-auditor.md` | Auth gaps, PII exposure, injection risks, attack surface |
| business-analyst | `personas/business-analyst.md` | Capability coverage, feature gaps, business rule completeness, user-journey gaps |
| performance-reviewer | `personas/performance-reviewer.md` | Hot paths, N+1 queries, synchronous blocking, unbounded queries |
| refactor-critic | `personas/refactor-critic.md` | Complexity hotspots, duplication, dead code, tech-debt surface |
| api-designer | `personas/api-designer.md` | Endpoint naming, REST/RPC convention consistency, versioning, error-shape uniformity |
| data-engineer | `personas/data-engineer.md` | Schema quality, migration hygiene, ORM query patterns, index candidates, FK integrity |
| qa-reviewer | `personas/qa-reviewer.md` | TESTS-edge coverage by module, untested critical paths, fixture hygiene |
| solutions-architect | `personas/solutions-architect.md` | Cross-service boundaries, inter-repo contracts, coupling, blast-radius (limited: cross_links coverage) |
| devops-reviewer | `personas/devops-reviewer.md` | CI/CD config, GitHub Actions pinning, build hygiene, graph-visible infra config (limited: no IaC indexer) |
| compliance-officer | `personas/compliance-officer.md` | PII field detection, audit-trail gaps, sensitive data flow surface scan (limited: name-match heuristics only) |
| dx-engineer | `personas/dx-engineer.md` | Test deserts, circular imports, god entry-points, module size outliers (limited: test/import-graph signals only) |

## Session state

Session state is persisted to `~/.grafel/sessions/<session-id>.yaml` using the host agent's `Read` and `Write` tools. No new MCP tools are required — all personas inherit `Read` and `Write` from the host agent.

### Schema

```yaml
session_id: <uuid-or-timestamp-slug>        # e.g. "20260527-143022-architect"
created: <iso8601>                           # e.g. "2026-05-27T14:30:22Z"
last_active: <iso8601>                       # updated on every save
active_persona: <name>                       # e.g. "architect"
consult_chain: [persona-a, persona-b]        # active Consult-Out chain at save time
context:
  original_ask: "<verbatim user question>"
  prior_findings:
    - persona: <name>
      summary: "<2-4 line text summary of that hop's findings>"
notes: |
  <free-form scratch — any persona may append mid-conversation>
```

### First-invocation flow (session picker)

On every invocation (unless `--new` or `--resume <id>` is passed):

1. Scan `~/.grafel/sessions/*.yaml` for files whose `last_active` is within the past 30 days.
2. If any active sessions exist, present them:
   ```
   Active sessions:
     [1] 20260527-143022-architect    last active: 2026-05-27  persona: architect
     [2] 20260525-091500-security     last active: 2026-05-25  persona: security-auditor
     [N] Start new session
   ```
   Ask: "Resume a session, or start new?"
3. If no active sessions exist (or the user picks "Start new session"), proceed to Persona selection below.

### Resume flow

When the user picks an existing session (or passes `--resume <session-id>`):

1. Read `~/.grafel/sessions/<session-id>.yaml`.
2. Re-prime the host agent:
   - Set `active_persona` to the saved value.
   - Inject the saved `context.original_ask`, `prior_findings`, `consult_chain`, and `notes` into the conversation as a system reminder block:
     ```
     [grafel-consult] RESUMING SESSION <session-id>
     Active persona: grafel-<name>
     Original ask: <original_ask>
     Prior findings: <prior_findings as bullet list>
     Consult chain: <consult_chain>
     Notes: <notes>
     ```
3. Activate the persona (load its body inline, same as a new hire).
4. Announce to the user:
   > Resumed session `<session-id>` with consultant `grafel-<name>`. Context restored. Pick up where you left off.

### Save flow

Session state is written under two conditions:

From cajasmota/grafel, MIT.

More from cajasmota/grafel