agentleFS
UfukCetinkaya57UfukCetinkaya57/backend-governance/.claude/skills/systematic-debugging/SKILL.md

systematic-debugging

Skill0 starsChanged 5 months agoMITView on GitHub

Bug, test hatasi veya beklenmeyen davranis ile karsilasinca, fix onerisinden ONCE kullan

190 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use chinese-code-review, chinese-commit-conventions and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Leodorareluctant259Skill

    chinese-code-review

    中文代码审查规范——在保持专业严谨的同时,用符合国内团队文化的方式给出有效反馈

    Also in 8 projects that use this

  • Leodorareluctant259Skill

    chinese-commit-conventions

    中文 Git 提交规范 — 适配国内团队的 commit message 规范和 changelog 自动化

    Also in 8 projects that use this

  • obraSkill

    diagnosing-superpowers

    Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.

    Also in 20 projects that use this

  • SethGammonSkill

    ascii-diagram

    Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.

    Also in 4 projects that use this

  • mjunaidcaSkill

    building-chatgpt-apps

    Guides creation of ChatGPT Apps with interactive widgets using OpenAI Apps SDK and MCP servers. Use when building ChatGPT custom apps with visual UI components, embedded widgets, or rich interactive experiences. Covers widget architecture, MCP server setup with FastMCP, response metadata, and Developer Mode configuration. NOT when building standard MCP servers without widgets (use building-mcp-servers skill instead).

    Also in 4 projects that use this

  • mjunaidcaSkill

    building-chat-interfaces

    Build AI chat interfaces with custom backends, authentication, and context injection. Use when integrating chat UI with AI agents, adding auth to chat, injecting user/page context, or implementing httpOnly cookie proxies. Covers ChatKitServer, useChatKit, and MCP auth patterns. NOT when building simple chatbots without persistence or custom agent integration.

    Also in 4 projects that use this

  • +2 more from Leodorareluctant259
  • +4 more from mjunaidca

The file

Files
SKILL.md

Sistematik Debugging

Temel Kural

FIX ONERISINDEN ONCE ROOT CAUSE ARASTIRILIR. ISTISNASI YOK.

Phase 1 tamamlanmadan fix onerisi YASAK.

Ne Zaman Kullanilir

  • Test hatalari
  • Production bug'lari
  • Beklenmeyen davranis
  • Performans sorunlari
  • Build/integration hatalari

Ozellikle su durumlarda: Zaman baskisi varsa, "bariz fix" gorunuyorsa, birden fazla fix denemis ama cozemediysen.

4 Faz

Her faz tamamlanmadan bir sonrakine gecilmez.

Faz 1: Root Cause Arastirmasi

Fix denemeden ONCE:

  1. Hata mesajini OKU — stack trace, satir numarasi, hata kodu. Atlamak YASAK.
  2. Yeniden uret — Ayni hatayi guvenilir sekilde tetikleyebiliyor musun? Edemiyorsan daha fazla veri topla, tahmin etme.
  3. Son degisiklikleri kontrol et — git diff, son commit'ler, yeni dependency, config degisiklikleri.
  4. Cok katmanli sistemlerde kanit topla:
    Her katman sinirinda:
      - Giren veriyi logla
      - Cikan veriyi logla
      - Ortam/config yayilimini dogrula
    Bir kez calistir → NEREDE kirildigini goster
    SONRA o katmani arastir
  5. Veri akisini izle — Hatali deger nereden geliyor? Geriye dogru izle, kaynagi bul. Belirtide degil, kaynakta duzelt.

Faz 2: Pattern Analizi

  1. Calisan ornekleri bul — Ayni codebase'de benzer ama calisan kod var mi?
  2. Referansla karsilastir — Pattern uyguluyorsan referansi TAMAMEN oku, gozu kaydirmak YASAK.
  3. Farklari listele — Calisan ve kirilan arasindaki her fark, ne kadar kucuk olursa olsun.
  4. Bagimliliklari anla — Hangi bilesenler, ayarlar, ortam gereksinimleri var?

Faz 3: Hipotez ve Test

  1. Tek hipotez kur — "X root cause, cunku Y" — acik, net, yazili.
  2. Minimal test yap — Tek bir degisken degistir, birden fazla seyi ayni anda degistirme.
  3. Dogrula:
    • Calisti? → Faz 4'e gec
    • Calismadi? → YENI hipotez kur, ustune fix ekleme

Faz 4: Uygulama

  1. Failing test yaz — En basit yeniden uretim. Otomasyon mumkunse test framework'u ile.
  2. Tek fix uygula — Root cause'a yonelik, TEK degisiklik. "Buradayken su da duzelse" YASAK.
  3. Dogrula — Test geciyor mu? Diger testler kirilmadi mi?
  4. Fix calismadiysa:
    • < 3 deneme: Faz 1'e don, yeni bilgiyle yeniden analiz et
    • = 3 deneme: DUR. Mimari sorun olabilir. Kullaniciya raporla, karar iste.

Kirmizi Bayraklar — DUR ve Faz 1'e Don

Su dusunceleri yakalarsan:

  • "Simdilik hizli fix, sonra incelerim"
  • "X'i degistirip deneyelim bakalim"
  • "Birden fazla degisiklik yapip test calistirayim"
  • "Test'i atlayip elle kontrol edeyim"
  • "Tam anlamadim ama bu calisiabilir"
  • "Bir fix daha deneyeyim" (zaten 2+ denemeden sonra)

Tumu = DUR. Faz 1'e don.

Yaygin Bahaneler

BahaneGercek
"Basit sorun, surece gerek yok"Basit sorunlarin da root cause'u var. Surec basit sorunlarda hizli.
"Acil, surece zaman yok"Sistematik debugging, rastgele deneme-yanilmadan HIZLI.
"Once sunu deneyeyim, sonra arastiririm"Ilk fix pattern'i belirler. Bastan dogru yap.
"Test'i fix'i dogruladiktan sonra yazarim"Test edilmemis fix'ler tutmaz. Once test, sonra fix.
"Birden fazla fix ayni anda zaman kazandirir"Hangisinin calistigini bilemezsin. Yeni bug'lar uretir.

Hizli Referans

FazAnahtar AktivitelerBasari Kriteri
1. Root CauseHata oku, yeniden uret, degisiklikleri kontrol etNE ve NEDEN'i anla
2. PatternCalisan ornekleri bul, karsilastirFarklari tespit et
3. HipotezTeori kur, minimal test etDogrulandi veya yeni hipotez
4. UygulamaTest yaz, duzelt, dogrulaBug cozuldu, testler geciyor

Gercek Dunya Etkisi

  • Sistematik yaklasim: 15-30 dk'da fix
  • Rastgele fix denemesi: 2-3 saat bocalama
  • Ilk seferde dogru fix orani: %95 vs %40
  • Yeni bug uretme: Neredeyse sifir vs yaygin

Kaynak: obra/superpowers (uyarlanmis versiyon)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.