Przejdź do treści
Biblioteka skilli
Programowanie · Konwersja i formaty

explain-diff

/explain-diff

Tłumaczy raport DriftReport w JSON na zrozumiały opis markdown do wklejenia w pull request, czat lub zgłoszenie błędu, bez wywołania LLM.

Repozytorium
nyann ↗
Licencja
MIT
Ostatnia zmiana repozytorium
22.08.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 22.08.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Tłumaczy raport DriftReport w JSON na zrozumiały opis markdown do wklejenia w pull request, czat lub zgłoszenie błędu, bez wywołania LLM.

Wyzwalacze z opisu

explain the driftsummarize doctor in plain Englishwhat does this drift report meannarrate the drifttranslate the drift reporthuman-readable drift
Oryginalny opis (EN)

Translate a DriftReport JSON into a plain-English markdown narrative suitable for pasting into a PR description, chat thread, or bug report. Read-only template render — no LLM call, no filesystem mutation. Pairs with `doctor` via the `--explain` flag, or runs standalone against any DriftReport produced by `bin/compute-drift.sh` / `bin/retrofit.sh --json` / `bin/doctor.sh --json`. TRIGGER when the user says "explain the drift", "summarize doctor in plain English", "what does this drift report mean", "narrate the drift", "translate the drift report", "human-readable drift", "explain what nyann f

Jak działa

  1. When to trigger
  2. When NOT to trigger
  3. Invocation
  4. Output shape
  5. Severity → lead-phrase mapping
  6. Reading the output back to the user
  7. Limits
Sekcje z nagłówków SKILL.md, w oryginale · 77 linii, 585 słów
Podgląd SKILL.md
---
name: explain-diff
description: >
  Translate a DriftReport JSON into a plain-English markdown narrative
  suitable for pasting into a PR description, chat thread, or bug
  report. Read-only template render — no LLM call, no filesystem
  mutation. Pairs with `doctor` via the `--explain` flag, or runs
  standalone against any DriftReport produced by `bin/compute-drift.sh`
  / `bin/retrofit.sh --json` / `bin/doctor.sh --json`.
  TRIGGER when the user says "explain the drift", "summarize doctor in
  plain English", "what does this drift report mean", "narrate the
  drift", "translate the drift report", "human-readable drift",
  "explain what nyann found", "make doctor output paste-friendly",
  "give me a drift summary for the PR", "/nyann:explain-diff".
  Do NOT trigger on "what's drifted" alone — that's `doctor` /
  `retrofit --report-only` (which produce the raw structured report
  this skill consumes). Do NOT trigger on "fix the drift" — that's
  `retrofit`.
arguments:
  - name: file
    description: Path to a DriftReport JSON file. Use `-` to read from stdin.
  - name: format
    description: Output format — `markdown` (default, human-readable) or `json` (DriftNarrative shape per schemas/drift-narrative.schema.json).
    optional: true
  - name: with-health
    description: Embed a health score (0-100) in the narrative header. Optional.
    optional: true
  - name: with-trend
    description: Embed a signed trend delta in the narrative header (e.g. `-8` for a 8-point regression). Optional.
    optional: true
---

# explain-diff

Read-only template render. Wraps `bin/explain-diff.sh`.

## When to trigger

- User has a DriftReport (from doctor / retrofit / compute-drift) and wants prose.
- User wants to paste a doctor summary into a PR body or chat without sharing raw JSON.
- User explicitly asks for "the drift in plain English".

## When NOT to trigger

- User is asking "is this repo healthy" → that's `doctor` (which can chain into this via `--explain`).
- User wants to mutate / fix → that's `retrofit`.
- User wants LLM-polished output → this skill is template-only by design (no LLM). If the user wants prose with more nuance, suggest reading the markdown output and editing by hand.

## Invocation

Three call shapes:

**1. Direct: file path**
```
bin/explain-diff.sh --file path/to/drift.json
```

**2. Pipe from a producer**
```
bin/compute-drift.sh --target . --profile default | bin/explain-diff.sh -
```

**3. Via doctor (recommended path)**
```
bin/doctor.sh --target . --profile default --explain
```

`doctor --explain` is preferred because it also forwards the computed health score and trend delta into the narrative header line — the same numbers text-mode shows at the foot of its output.

`--explain` is mutually exclusive with `--json` on doctor; if both are passed, doctor dies with a clear error.

## Output shape

**Markdown (default)** — three sections:

1. **Header** — target + profile + (optional) health score + trend
2. **What's drifted** — one bullet per drift category, ordered by severity. Each bullet has a lead phrase (`Action required:`, `Worth fixing:`, `Drifted:`, `Minor:`) and up to 5 concrete items. If a category has more than 5 items, an "...and N more" line appears.
3. **What you can do** — ordered action items that map to nyann skills (`nyann:retrofit`, `nyann:optimize-claudemd`, etc.)

**JSON (`--format json`)** — the DriftNarrative shape (`schemas/drift-narrative.schema.json`). Useful for chat-bot integrations or custom renderers that want the same source-of-truth without re-parsing the prose.

## Severity → lead-phrase mapping

| Severity | Lead | Sources |
|---|---|---|
| critical | "Action required:" | `missing[]`, broken links, `claude_md=error` |
| high | "Worth fixing:" | `misconfigured[]`, `claude_md=warn` / `absent`, subsystem errors |
| medium | "Drifted:" | `orphans`, staleness, `misplaced[]` |
| low | "Minor:" | non-compliant history (informational; nyann doesn't rewrite history) |
| info | (suppressed in markdown) | reserved for downstream filtering via the JSON shape |

The mapping is intentionally fixed (no profile-level override) so a narrative pasted into a PR reads the same regardless of which profile produced the underlying report.

## Reading the output back to the user

When the user asks for "the drift in plain English":

- Print the markdown block as-is. It's already formatted for human consumption.
- If the user asks for a "one-line summary" instead, count the `## What's drifted` bullets — the section count IS the summary number. E.g. "3 categories drifted: hooks (critical), claude_md (high), history (informational)."
- If the user asks "should I worry about Minor items" → no, those are CC-style informational checks; nyann doesn't rewrite history.
- If the report is clean (no `## What's drifted` section appears), the narrative says so explicitly — don't editorialise.

## Limits

- Template-only. No LLM smoothing — accept slightly mechanical phrasing as the cost of offline-safe rendering.
- Per-section items capped at 5 in the markdown output; the full list is in the JSON shape if a consumer needs it.
- Health score / trend are optional — if the caller doesn't supply them, the score line is suppressed (not faked to zero).

Wersje

RepozytoriumWynikLicencja
Ta strona · thettwe/nyann100MIT
chanmuzi/git-claw100MIT
checkpickerupper/skills100MIT
nicknisi/claude-plugins100MIT
filip-podstavec/claude-leverage100MIT

Migawka bazy z 13.11.2026 · wersja paczki 6ace1cfd9e0c (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90diagnose
    Zbiera zanonimizowaną migawkę stanu nyann do zgłoszenia błędu: explain-state, doctor, konfigurację git i użytkownika bez tokenów, hooki oraz check-prereqs w jednym podsumowaniu JSON lub tekstowym.
  • 100explain-this-pr
    Bierze URL pull requesta z GitHuba lub bieżącą gałąź, pisze prosty opis, co zmiana robi i dlaczego, i publikuje go jako komentarz do PR.
  • 90diff-explain
    Opisuje zwięzłym akapitem prostym językiem, co robi dany diff, pull request lub gałąź.
  • 100doctor
    Przeprowadza audyt higieny i dokumentacji bieżącego repozytorium tylko do odczytu: wykrywa rozjazdy, uszkodzone elementy, zdezaktualizowaną dokumentację i brakujące hooki.
  • 100simple-issue-description
    Przekształca surowe zgłoszenie błędu, prośbę o funkcję lub opis pull requesta w krótkie zgłoszenie prostym językiem, skupione na problemie i oczekiwanym zachowaniu.
  • 100n8n-doctor
    Sprawdza i naprawia workflowy n8n z wyeksportowanego JSON-a, a na żywej instancji analizuje nieudane wykonania bez zmian.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.