القائمة
Use when writing or designing code: name premise and blast radius, deepen modules at seams, TDD at agreed seams, diagnose before patching, and keep producer→consumer contracts honest.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | do-it-code-quality |
| description | Use when writing or designing code: name premise and blast radius, deepen modules at seams, TDD at agreed seams, diagnose before patching, and keep producer→consumer contracts honest. |
Main defense while writing. Prefer depth, locality, and real feedback over ceremony.
Leading words (use them): deep module, seam, tracer bullet, red before green, scope chain.
Detail: ../references/scope-chain.md.
Prefer deep modules: small interface, rich implementation, at a clean seam (Feathers).
| Term | Meaning |
|---|---|
| Depth | Behavior callable per unit of interface the caller must learn |
| Leverage | Callers get more capability per learned interface |
| Locality | Change/bugs/verification concentrate in one place |
| Adapter | Concrete thing that satisfies an interface at a seam |
Comments answer what the next reader must know that code cannot say.
Allowed: tool docstrings; // @anchor:<id>; // see also: <path>; // invariant: ...; real tool directives with a reason.
Forbidden: what-comments, history/fix narrative, ticket refs, tombstones, orphan TODOs (need TODO(@owner): <closing condition>).
When changing behavior and a RED test is practical:
Anti-patterns (reject):
expect(f(a,b)).toBe(a+b))Mechanical/docs edits may skip RED — state why.
Symptom → reproduce → one hypothesis → falsify with the smallest check → fix the cause → regression proof. Three failed patches → question the design before another try.
Optimize from evidence, not assumed limits. Unknown is not impossible: establish a measured baseline, preserve a correct fallback, then test a plausible breakthrough path. Before investing deeply, run the cheapest falsifier that could disprove the key premise; promote the idea only when observed results beat the baseline on the metric that matters.
A feature bound for production is not done until its evidence surface is named — the log line, metric, or trace that will show it alive or failing there.
Use a separate worktree only for genuinely parallel, risky, or conflicting work — not a bounded one-thread change. The parent owns shared files and integration.
Merge conflicts resolve hunk by hunk, by intent: trace each side to its source (commit, PR, issue) and preserve both intents where possible; where they truly collide, follow the merge's stated goal and note the trade-off. Never escape via --abort or wholesale --ours/--theirs. Finish the operation, then run the project's checks.
Public/API/schema or cross-package work needs both-side mapping: ownership and dependency direction, compatibility/rollback effect, producer → consumer proof path, and the smallest boundary check. Stop when a proposed new surface has no consumer.
Map the proof path. Do not invent APIs/exports/events without an in-task consumer. Schema/API changes need both sides.
Rewrite when you notice: as any / @ts-ignore, over-mock, swallowed errors, unused exports, cover-up edits.
Advisory hook families: ../references/write-quality-families.md.
NEEDS_CONTEXT / BLOCKED when premise cannot be verified locally, the fix crosses unassigned boundaries, or a new surface has no consumer.
Use when premises or options must be pressure-tested, a short plan/handoff is needed, or a large plan must be sliced — grill facts locally, ask decisions one at a time.
Use when a project needs a lean `.do-it/handbook/` for stable project truth plus `.do-it/worklog/` for daily or goal notes.
Use before any done, fixed, passing, ready, install, or merge claim, and when closing a branch — fresh evidence on this worktree; hooks vary by host, this skill is the checklist.
Use only when the user explicitly asks to enable, disable, inspect, report, or persist opt-in local do-it behavioral feedback.
Use when starting any non-trivial repo task: pick Light / Standard / Heavy tier, then self-select meaning skills — not a fixed pipeline.
Use when repo terms or invariants are drifting, or when user/docs/code naming disagrees and a canonical glossary is needed — `.do-it/CONTEXT.md` is the downstream source of truth for names, relationships, and facts.