القائمة
Surface architectural friction, propose deepening opportunities. Use when user wants to clean up or improve the codebase architecture or design.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Exercise software as real consumer would — docs-first walkthrough, full public surface coverage, adversarial misuse — producing a ranked friction report. Works for any software type (library, CLI, server/API, web UI, TUI). Use when user says "dogfood", "exercise as a consumer/user", "friction report", "consumer trial", "try it like a real user", or as harden skill Phase 1 (Exercise → friction). Re-eval mode re-runs a prior report for a resolved/still-live delta.
Iterative refinement loop for taking a change to a high quality bar. Sequences exercise→friction, grill→decide, TDD slices, then review→soundness→simplify→architecture→test-health→docs passes — repeating until a full round finds nothing significant — under fixed discipline (authority docs sacred, commit per slice, verify every slice, reverse your own calls on evidence, capture decisions durably). Use when the user wants to build or refine something "properly", harden a change, run a multi-pass quality loop, evaluate an API as a real consumer, or asks to "harden", "do this properly", "full quality pass", "refine loop", "keep going until clean", or "production-grade" work. Gated — stops for the user's call at authority conflicts, fix decisions, architecture do/decline, and irreversible actions.
MUST be used for every git commit. Formats Conventional Commit messages, checks for breaking changes, and stages files atomically.
Collaborative specification refinement through codebase analysis, discovery interviews, and iterative red-teaming. Use when user wants to write a spec, refine requirements, design a feature, or mentions "spec", "requirements", "PRD", or "specification".
Break a plan or spec into vertical-slice tasks. Use when user wants to break down work into tasks, slice a spec into implementable pieces, or mentions "to-tasks", "break down", "task breakdown", or "slice".
Audit and improve a user-facing entry doc (README, docs-site landing, man-page intro, getting-started guide) for factual accuracy and for three reader audiences — evaluator, newcomer, returner. Use when asked to "improve/proofread/audit the readme (or docs)", "is my readme any good", "make the docs clearer / more motivating", or to check docs for stale/inaccurate information.
| name | improve-codebase-architecture |
| description | Surface architectural friction, propose deepening opportunities. Use when user wants to clean up or improve the codebase architecture or design. |
Surface friction, propose deepening opportunities — refactors that increase depth, cohesion, locality while reducing coupling.
Load references progressively — only when entering the phase that needs them. Do not front-load all references at skill activation.
| When | Load |
|---|---|
| Skill activation | LANGUAGE.md (vocabulary for all phases) |
| Step 1 — Explore | ANTI-PATTERNS.md |
| Step 1b — Evidence | EVIDENCE.md |
| Step 3 — Grill | PATTERN-GUIDE.md, DEEPENING.md |
| Step 4 — Design | INTERFACE-DESIGN.md |
| Step 6 — Proposal | PROPOSAL-TEMPLATE.md |
If user jumps directly to a step, load that step's references + all prior unloaded ones.
Terms in references/LANGUAGE.md. Use exactly — no "service," "component," "controller," "boundary."
Read CONTEXT.md + docs/adr/ before exploring. Proceed silently if absent.
Core principles: deletion test (delete module → complexity vanishes = pass-through, reappears across callers = earning keep). Interface = test surface. One adapter = hypothetical seam; two = real. Deep = testable at boundary.
Scale: <5k LOC → lightweight, skip sub-agents. 5k–50k → full process. >50k → scope to one context per session.
Skip when: <5 commits/6mo, 1–2 callers, scheduled for deletion, no test pain, deadline pressure. Note skip reason for future reviews. DO NOT SKIP IF USER EXPLICITLY ASKS FOR REVIEW OF THAT SEAM.
Navigate organically. Note: shallow modules, scattered understanding, coupling leaks, untestable interfaces. Flag hot paths and concurrency boundaries.
Apply deletion test to suspect modules. Check references/ANTI-PATTERNS.md.
Collect quantitative signals before presenting candidates. Details + commands in references/EVIDENCE.md:
Gather what's practical — not every signal available in every project.
Numbered list, ranked by priority (impact + risk). Per candidate:
Use CONTEXT.md domain language. Flag ADR contradictions only when friction is real. Do NOT propose interfaces — ask which to explore.
Walk design tree: interface constraints, dependencies, hidden complexity, test strategy (references/PATTERN-GUIDE.md, references/DEEPENING.md).
Side effects: new concept → add to CONTEXT.md. Sharpened term → update CONTEXT.md. Load-bearing rejection → offer ADR (see /domain-model for CONTEXT.md and ADR formats, three-gate ADR check).
Simple → propose one interface from grilling constraints. Ambiguous/Complex → parallel sub-agents (see references/INTERFACE-DESIGN.md).
Use template in references/PROPOSAL-TEMPLATE.md: Problem, Proposed Interface, Architecture Decisions, Testing Strategy, Migration Plan (branch by abstraction/strangler fig → migrate callers → deepen → clean up), Implementation Recommendations.
After implementation: re-run deletion test, compare test counts (fewer at tighter interface = success), check fan-in/fan-out delta, spot-check locality (fewer files per change).
Marginal improvement = data for future sessions, not failure.
For code-level cleanup after architectural changes, run /simplify.
