
# Scoping Service Skills ( /scope )

> Detailed **scope / route** flow (intent detection, scope plan, regression-test binding) for the `service-skills` router.
>
> **Path model:** `.claude/skills/<service>/SKILL.md` shown below is the **Claude-Code view** (a symlink). The canonical home for per-service skills is under `.xtrm/skills/user/packs/<pack>/` — scripts resolve it via `bootstrap.get_service_skill_path_str`. Machinery scripts live at `.claude/skills/service-skills/scripts/` (the active view of this skill).

Ground every task in the right expert context **before any files are touched**.

## Trigger

User types `/scope "task description"` — or `/scope` with task context already
in the conversation.

---

## Execution Flow

### Step 1 — Read the Registry

Run this at the start, before deep task reasoning:

```bash
python3 "$CLAUDE_PROJECT_DIR/.claude/skills/service-skills/scripts/scope.py"
```

This outputs every registered service: ID, container, territory paths, skill path,
and description. If the registry is missing, report:

> "No service-registry.json found at this project. Run /creating-service-skills first."

---

### Step 2 — Detect Intent

Scan the task description for keywords:

| Intent | Signal keywords |
|---|---|
| `investigation` | broken, error, failing, problem, not working, issue, crash, down, missing, slow, 502, 404, 429, timeout |
| `feature` | add, implement, create, new, build, introduce, support |
| `refactor` | refactor, restructure, clean, reorganize, simplify, rename, extract |
| `config-change` | update, change, modify, set, configure, adjust, tune |
| `exploration` | how, explain, understand, what is, show me, why, walk me through |

**Default when ambiguous → `investigation`** (safer: check first, act second).

---

### Step 3 — Map to Services

Using the registry output, reason about which service(s) the task involves. Match on:

- Explicit service name in task description (`traefik`, `grafana`, `loki` …)
- Symptom-to-service knowledge:
  - `502 / route not found` → traefik
  - `logs not appearing` → loki / promtail
  - `alert not firing` → alertmanager / prometheus
  - `dashboard broken` → grafana
  - `API key rejected` → api-gateway
  - `disk full` → node-exporter / loki (chunks)
  - `container memory` → cadvisor
- Config file or directory mentioned (`routes.yml` → traefik, `prometheus.yml` → prometheus)
- Container name mentioned (`infra-*`)

**Refine with the graph when the symbol/flow is ambiguous.** Territory globs route by file
path; when a task names a *symbol* or *behavior* rather than a path, confirm ownership with
GitNexus before committing the scope (the `scope.py` footer prints these when an index exists):

```bash
gitnexus query "<task concept>" --repo <name>      # which execution flow / service owns it
gitnexus impact <symbol> --direction upstream       # if the change reaches multiple services, scope them all
```

If a service's `Last sync` (shown by `scope.py`) is far behind, treat its SKILL.md as
possibly stale and lean on the graph + source over the doc. With no index, route by globs.

---

### Step 4 — Output XML Scope Block

Emit this block before moving into implementation:

```xml
<scope>
  <task>"user's original description"</task>
  <intent>investigation</intent>
  <confidence>high|medium|low</confidence>
  <services>
    <service id="traefik" confidence="high">
      <reason>user mentioned 502 on dashboard route</reason>
      <skill>.claude/skills/traefik/SKILL.md</skill>
      <load>now</load>
    </service>
  </services>
  <workflow>
    <phase order="1" name="diagnose">
      Consult traefik SKILL.md failure modes table.
      Run health_probe.py and log_hunter.py before any ad-hoc docker commands.
    </phase>
    <phase order="2" name="fix">
      Apply targeted fix based on diagnosis.
    </phase>
    <phase order="3" name="regression-test">
      <decision>
        Code behavior bug → write test in repo test suite (pytest/unit).
        Operational/infra issue → extend health_probe.py OR add script to
          .claude/skills/traefik/scripts/.
      </decision>
      Name the function after the failure mode it catches.
      Commit the test alongside the fix — never separately.
    </phase>
  </workflow>
</scope>
```

Adapt the phases to the detected intent (see Intent Workflows below).

---

### Step 5 — Load Skills

For each `<service>` with `<load>now</load>`, immediately read the skill file:

```
Read: .claude/skills/<service-id>/SKILL.md
```

Load all matched skills before proceeding with the task.
Adopt the expert persona, constraints, and diagnostic approach from each loaded skill.

---

### Step 6 — Execute

Follow the workflow phases in order. For `investigation` tasks, include the
regression-test phase — it keeps fixes durable.

---

## Intent Workflows

### `investigation` — Problem / Error / Broken

```
diagnose → fix → regression-test
```

- Start with the skill's **failure modes table** — not ad-hoc docker commands.
- Use the skill's **diagnostic scripts** (`health_probe.py`, `log_hunter.py`) first.
- After the fix is applied and verified: write a regression test (see below).

### `feature` — New Capability

```
design → skill-check → implement → test
```

- Read the skill's **architecture section** before designing anything.
- Check integration points (what calls this service, what does it call).
- Write tests alongside implementation, not as a follow-up.

### `refactor` — Structural Change

```
scope → skill-check → change → verify
```

- Read the skill's **integration diagram** to understand what depends on this.
- Use `find_referencing_symbols` before renaming or restructuring.
- Verify no external callers break after the change.

### `config-change` — Setting / Parameter

```
read-current → validate → modify → confirm
```

- Read the current config state before touching anything.
- Validate the intended change against the skill's known constraints and limits.
- After applying: confirm the service is healthy (`health_probe.py`).

### `exploration` — Understanding / Analysis

```
load-skill → answer
```

- Load the skill and answer from its documented knowledge.
- No file modification. No action needed unless user explicitly asks.

---

## Regression Test Binding

When `intent = investigation` and a fix has been applied, write a regression
test. Use this decision tree:

```
Is the bug in application code logic?
  YES → write pytest/unit test in repo's test suite

  NO  (operational / infra / config issue) →
        Does the skill's health_probe.py already check this condition?
          YES → extend the existing check function
          NO  → add a new check function to health_probe.py
                OR create a dedicated script in .claude/skills/<service>/scripts/
```

**Naming convention** — name after the failure mode, not the fix:

```python
def check_route_not_returning_502():    # ✅ descriptive
def check_cert_not_expiring_soon():     # ✅ descriptive
def test_fix():                         # ❌ meaningless
def test_issue_123():                   # ❌ meaningless
```

Commit the test in the same commit as the fix.

---

## No Match Handling

If no registered service matches the task:

1. Report: `"No registered skill covers this area."`
2. Offer: `"I can create one — use /creating-service-skills."`
3. Fall back to general expert mode (no skill enforcement).

---

## Related Skills

- `/using-service-skills` — Passive catalog at session start
- `/creating-service-skills` — Scaffold new expert skill packages
- `/updating-service-skills` — Sync skills after implementation drift
