Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

refactoring-planning

/refactoring-planning

Zamienia diagnozę architektury w uporządkowany plan refaktoryzacji z kolejnością napraw i zadaniami przygotowanymi do dalszego planowania.

Repozytorium
tearags-mcp ↗
Licencja
MIT
Ostatnia zmiana repozytorium
10.11.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 10.11.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

Zamienia diagnozę architektury w uporządkowany plan refaktoryzacji z kolejnością napraw i zadaniami przygotowanymi do dalszego planowania.

Wyzwalacze z opisu

plan a refactoringplan the architecture fixfix order for these violationsrefactoring roadmapспланируй рефакторингв каком порядке чинить нарушения
Oryginalny opis (EN)

Turn architecture diagnosis into an ordered, simulated refactoring plan — restructure ops per finding, ordered by tier, handed to writing-plans as Tasks. Use when asked "plan a refactoring", "plan the architecture fix", "fix order for these violations", "refactoring roadmap", "спланируй рефакторинг", "в каком порядке чинить нарушения" — NOT for diagnosis alone (use architecture-diagnostics), NOT for one in-file change (use data-driven-generation), NOT for code health scan (use risk-assessment).

Jak działa

  1. Phase Order (MANDATORY)
  2. Top Anti-patterns
  3. Phase 0 — GATE
  4. Phase 1 — REPORT
  5. Phase 2 — CANDIDATES
  6. Phase 3 — ORDER
  7. Phase 4 — ANNOTATE
  8. Phase 5 — PLAN
  9. Phase 6 — EXECUTION CONTRACT
  10. Output
Sekcje z nagłówków SKILL.md, w oryginale · 187 linii, 1 270 słów
Podgląd SKILL.md
---
name: refactoring-planning
description:
  'Turn architecture diagnosis into an ordered, simulated refactoring plan —
  restructure ops per finding, ordered by tier, handed to writing-plans as
  Tasks. Use when asked "plan a refactoring", "plan the architecture fix", "fix
  order for these violations", "refactoring roadmap", "спланируй рефакторинг",
  "в каком порядке чинить нарушения" — NOT for diagnosis alone (use
  architecture-diagnostics), NOT for one in-file change (use
  data-driven-generation), NOT for code health scan (use risk-assessment).'
---

# Refactoring Planning

> **Resources in Cursor:** if a `tea-rags://` resource cannot be read (no
> resource tool, or the read fails), run
> `tea-rags resource "<uri>" --path "$PWD"` in the terminal — same content.

Diagnosis → simulated candidates → server-ordered steps → plan Tasks w/ expected
delta. Server orders; agent builds candidates + plan. Execute YOURSELF, tea-rags
tools only.

Lag / drift ≠ licence to leave tea-rags (core). Own checkout, `changedFiles` > 0
→ incremental `index_codebase`; subagent / linked worktree → never reindex. →
`tea-rags://guide/freshness`.

## Phase Order (MANDATORY)

0. GATE — codegraph on?
1. REPORT — one `get_architecture_report`
2. CANDIDATES — recipe per critical/active finding; lexicon + `plannedEdges`
3. ORDER — `restructurePlan` (report candidates per cost rule)
4. ANNOTATE — `/refactoring-scan`, notes only
5. PLAN — `writing-plans`, one step = one Task
6. EXECUTION CONTRACT — written into plan

## Top Anti-patterns

- Prose remedy / file move where recipe gives edge ops → no candidate.
- Plan Task w/o `restructurePlan` simulation behind it.
- MISFIT edge proposed. `UNJUDGED newFile` treated as reject (it is not).
- Trade-off / unselected / deferred → Task. Never.
- Scan hit reorders steps or adds own Task.
- `includeReportCandidates` default on large repo → call runs ~1 h (bd
  tea-rags-mcp-vytjl).
- Plan Task w/o expected delta, or plan w/o execution contract.
- Diverged Task → next Task on stale plan.

## Phase 0 — GATE

Codegraph on = graph tools (`get_callers`, `trace_path`, …) in tool list; absent
= off. Off → "refactoring planning needs codegraph", stop. Any plan-mode answer
`unavailable: "noCodegraph"` → stop, same line.

## Phase 1 — REPORT

`get_architecture_report(path: "<working dir>", pathPattern?|domain?, limit?)` —
reading per `/architecture-diagnostics` Phase 1 (do not restate). Keep:

- findings w/ `tier` critical / active (SDP, leakingAbstraction, layering
  backEdge, hubLikeDependency). Structural-only → listed, no candidate unless
  user asks. `summary.impactTiers` `built: false` → untiered: take by
  `maintenanceCost`, say "untiered".
- `N` = `summary.propagationCost.fileCount` (judged production files — drives
  per-judge cost).
- `R` = `summary.splitMerge` split + merge candidates (report candidates
  `restructurePlan` adds). Block not built → R = 0.
- Totals > rows returned, or `truncated` present → page the held report
  (`reportId`, per architecture-diagnostics Phase 1) BEFORE Phase 2 caps
  candidates — a critical finding on page 2 is still a candidate.

User already ran architecture-diagnostics this session → reuse that report, no
re-call.

## Phase 2 — CANDIDATES

Per kept finding: load `../../repair/<family>.md` `## Ops recipe` — that family
only, never preload dir.

| Finding                     | Recipe file                                |
| --------------------------- | ------------------------------------------ |
| `stableDependencies`        | `stableDependencies.md`                    |
| `hubLikeDependency`         | `hubLike.md`                               |
| `leakingAbstraction`        | `leakingAbstraction.md`                    |
| `layering` backEdge         | `layeringBackEdge.md`                      |
| layer-map move / A5 verdict | architecture-diagnostics Phase 3i op table |

- Recipe → ops verbatim shape: `removeEdge{from,to}`,
  `addFile{file,component, abstract: true}` for extracted interface,
  `addEdge{from,to}`, `move{…}`. Paths repo-relative base paths; new-file path
  per recipe's path rule (never hard-coded dir). SDP inversion: A = finding's
  `sourceRelPath`, B = its `toRelPath` — FILES, never the component dirs of the
  finding key; spelled: `removeEdge{A,B}`,
  `addFile{<foundation>/…/<Iface>.ts, abstract: true}`, `addEdge{A,iface}`,
  `addEdge{B,iface}` — rationale = finding key.
- Recipe says "no recipe, escalate" → no candidate; list under Escalated.
- Names: ONE `get_naming_lexicon` call over all drafted new-file / type names.
  `MISFIT` / `COLLISION` → rename to suggestion; `NEW_TERM` → keep + one-line
  why.
- Edges: ONE `get_architecture_report(path, plannedEdges: [...])` over every
  `addEdge` between EXISTING files. `MISFIT` → drop candidate, line
  `DROPPED <id> — MISFIT <src> -> <dst> (established <roleSrc> -> <roleDst>, support <n>)`.
  `UNJUDGED newFile` / `NEW_PATTERN` / `CONFORMS` → keep.
- Candidate = `{id, rationale: <finding key>, ops}` — one per remedy, ≤ 20 ops.
  `rationale` = the finding `key` string verbatim (e.g.
  `stableDependencies:<A dir>-><B dir>`), not prose. Write each candidate out in
  the answer: every op with its concrete paths, the new file under the
  foundation component — never "form candidate from recipe". `id` kebab
  `<family>-<short subject>`, never `report:` prefix (server owns it).
- Cap ≤ 15 candidates per plan call: critical first, then active, then
  `maintenanceCost`. Rest → Deferred (re-plan after first Tasks land).

## Phase 3 — ORDER

`get_architecture_report(path, restructurePlan: {candidates, includeReportCandidates})`
— only `limit` may ride along.

Cost: rounds = steps + 1, each round judges every remaining candidate (full
detector run) → judges ≈ (S + 2)·(K + R). Per-judge ms grows w/ N. Known per
judge = `(timing.totalMs − timing.factsMs) / timing.judgeCount` of an earlier
plan / restructure call this session.

1. R = 0 → one call, own candidates, flag irrelevant.
2. R > 0, no per-judge measurement yet → first call
   `includeReportCandidates: false` (always safe), ≤ 15 own candidates (critical
   first; rest Deferred — never all of them). It yields S + per-judge.
3. Estimate (S + 2)·(K + R)·perJudge + factsMs. ≤ ~2 min (one MCP call) →
   re-call same candidates, `includeReportCandidates` omitted (true); that plan
   supersedes. Over → large repo: keep the `false` plan, say verbatim (bd id
   included) "report split/merge candidates not ordered — quadratic judging,
   call can run ~1 h (bd tea-rags-mcp-vytjl)", list them under Not ordered (each
   simulable alone via architecture-diagnostics Phase 3i). Never drop them
   silently.

Large repo = estimate over budget; N ≥ ~10k judged files with dozens of R → skip
the estimate, go `false` directly — still ≤ 15 candidates, and say why citing bd
tea-rags-mcp-vytjl.

Read response: `steps[]` (order = plan order; `delta` vs prefix, `byTier`,
`touchedFiles`, `blastRadius`), `tradeOffs[]` (introduce critical/active — never
selected), `unselected[]` (`noImprovement` | `conflictsWithPrefix` + `detail`),
`total` (base vs final prefix). Unknown file / edge → typed error
(`INPUT_UNKNOWN_RESTRUCTURE_*`) → fix name, re-call; never drop candidate.

## Phase 4 — ANNOTATE

`/refactoring-scan` over union of steps' `touchedFiles`. Tier 1/2 hit on file F
in step k → note on step k: "F — decompose too (<signals>)". Order unchanged; no
Task added; no step removed.

## Phase 5 — PLAN

`writing-plans`. One step = one Task, step order. Per Task:

- `candidateId`, `rationale` (finding key), ops as implementation intent (remove
  import A→B, extract interface I at path, A + B import I).
- **Expected delta** = step `delta`: resolved subjects, introduced subjects
  (none or listed), `byTier`, `net`; `blastRadius`; scan note if any.
- Implementation via `/data-driven-generation`; Task ends w/ DDG Step 7 gate
  line, quoted literally in the Task:
  `GATE review_changes: introduced=<n>, partial=<true|false>`.

Separate sections, NEVER Tasks: **Trade-offs** (candidate, introduced vs
resolved by tier), **Unselected** (candidate, reason, detail), **Not ordered**
(report candidates on large repo), **Deferred** (over cap), **Escalated** (no
recipe), **Dropped** (MISFIT).

## Phase 6 — EXECUTION CONTRACT

Write this block into every generated plan, verbatim:

```text
Execution contract (refactoring-planning):
1. After each Task: review_changes(changes: {base: <commit before this Task>},
   sections: ["architecture"]) — compare change.resolved and introduced
   (findings + change.nonLocal) with the Task's expected delta.
2. Match → DDG Step 7 gate line, commit, next Task.
3. Diverged (expected resolved missing, or unexpected introduced) → DDG Step 7
   fix-at-write loop (≤ 2 rounds).
4. Not converging → get_architecture_report(path: <working dir>,
   restructurePlan: {candidates: <remaining Tasks' candidates>}) on the real
   tree; replace remaining Tasks with the new steps + expected deltas.
   Never continue on the stale plan.
```

## Output

Show, never summarize: candidate ops with paths, Task expected delta, the gate
line and the Phase 6 contract block appear in the answer as text — "Task
includes expected delta and execution contract" is not the plan.

```text
## Plan — <scope>: <S> steps, total net <n> (critical <r>/<i>, active <r>/<i>, structural <r>/<i>)
| # | Candidate | Rationale | Expected resolved | Introduced | byTier | Blast | Note |
## Trade-offs / Unselected / Not ordered / Deferred / Escalated / Dropped
Plan file: <path from writing-plans>
```

Wersje

RepozytoriumWynikLicencja
Ta strona · artk0de/tearags-mcp100MIT
artk0de/tearags-mcp100MIT
artk0de/tearags-mcp100MIT

Migawka bazy z 13.11.2026 · wersja paczki c18139f95f4a (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

  • 100change-planning
    Zamienia uzgodnioną przyczynę źródłową w uporządkowany plan z etapami, weryfikacją i bramką zatwierdzenia.
  • 100refactoring-guide
    Przygotowuje rekomendacje refaktoryzacji według Fowlera z konkretnymi technikami, oceną ryzyka i planem krok po kroku, gdy kod wymaga restrukturyzacji.
  • 100dev-code-quality
    Skanuje bazę kodu pod kątem duplikacji, nadmiarowości i możliwości poprawy, wskazując cele refaktoryzacji i ogólny stan kodu.
  • 100test-prioritization-handoff
    Zamienia wynik rozpoznania w uporządkowany plan testów z kolejnością i uzasadnieniem każdej pozycji.
  • 100writing-plans
    Zamienia specyfikację techniczną, odwołanie do trackera lub prośbę o funkcję w atomowy plan wdrożenia uporządkowany zależnościami, zapisany jako plik Markdown w .plans/ dla agenta kodującego.
  • 100architecture-diagnostics
    Diagnozuje naruszenia zależności i warstw oraz wskazuje kandydatów do przeniesienia, gdy użytkownik wyraźnie o to poprosi.

Uwagi i zgłoszenia

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