菜单
Use when implementing a feature that needs changes in underlying layers, when reviewing code, when refactoring or migrating, or when discussing a technical design.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/boukeversteegh/tractor --skill architecture命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Deep technical analysis of a GitHub issue for complexity assessment and implementation planning. Traces code paths, assesses design impact, finds related work. Use when the user wants to understand an issue before working on it.
Fire-and-forget issue triage. Runs the analyze workflow, posts findings as a GitHub comment with expandable sections, and sets the size/* label. Use when the user wants to quickly triage a GitHub issue without interactive discussion.
Write or update GitHub release notes for tractor. Use when creating a new release, updating existing release descriptions, or reviewing release notes quality.
正在显示 SKILL.md
| name | architecture |
| author | boukeversteegh |
| description | Use when implementing a feature that needs changes in underlying layers, when reviewing code, when refactoring or migrating, or when discussing a technical design. |
Portable methodology — no project-specific paths or conventions inside.
Reach for this skill when:
It guides the agent to extract invariants first, assign clear ownership boundaries, refactor structure before layering on patches when needed, normalize inputs once, remove bypasses and duplication, implement in stable incremental slices, and validate behavior with semantic tests before broad snapshots and doc updates. It is especially useful when there is risk of local fixes causing architectural drift, concern leakage, inconsistent behavior across entry points or output forms, or an end result with more factors rather than fewer.
This workflow is for complex tasks that involve feature work, refactoring, architectural changes, migration behavior, or broad plumbing across a codebase.
Its goal is not just to make the task "work." Its goal is to leave the codebase simpler, more coherent, and easier to extend than before.
Treat the task as a system-design problem first and an editing problem second.
Before changing code, answer these questions:
Do not begin by patching the first visible symptom.
Before fixing a bug, ask: is this an instance of a class?
If the component you're fixing is one of several with the same role (caches, retries, validators, serializers, rate limiters, auth checks, deserialization paths), the defect is likely shared. The locality is often an illusion — you noticed it here because this is where it surfaced, not because this is where it lives.
Do this:
A one-spot fix to a class-level bug guarantees you will fix it again, differently, in each sibling — and the inconsistencies between those fixes become their own architectural problem.
The same prompt applies when adding behavior: if the new behavior is the kind of thing every sibling should also have (e.g. single-flight load coalescing on a cache, timeout on an outbound call, idempotency on a write), deciding now is cheaper than retrofitting later.
Read the task, design notes, failing tests, and surrounding code until you can write a short list of global truths.
Examples of good invariants:
A good invariant is:
If you cannot state the invariants clearly, you are not ready to implement.
For each important concern, decide where it belongs.
Common concerns to assign:
Use this rule:
A concern should have one obvious owner.
Warning signs that ownership is broken:
If ownership is unclear, fix structure before adding more logic.
Refactor first when one or more of these are true:
Do not preserve bad structure just because it already exists.
If the old structure fights the new concept, the refactor is part of the feature.
Break the task into slices where each slice establishes a stable improvement.
Good slice types:
Avoid slices that are only "some edits in many places." Each slice should have a purpose that can be described in one sentence.
Preferred order:
This order reduces rework because later decisions are made on a cleaner foundation.
Do not implement surface behavior first if the infrastructure underneath is known to be wrong.
Complex systems often fail at boundaries.
When flags, modes, config, defaults, and implicit behavior interact, create one normalization step that produces an internal plan.
That plan should answer questions such as:
Rules for normalization:
If multiple downstream layers must "figure out what the user meant," the normalization is incomplete.
"Normalize once" says where normalization happens. It does not say what a function should do when its own correctness depends on having received a normalized value. That is a separate question, and answering it with "the caller will have done it" is how the invariant dies.
If a function is only correct for normalized input, it owns that requirement. Two ways to discharge it, in order of preference:
What not to do is rely on a convention. A function that takes the raw type and is correct only because every current caller happens to normalize first is one new caller away from a silent wrong answer — and that caller will look correct in review, because nothing at the call site says otherwise.
The tell is a value that some callers normalize and others do not, flowing into one function. When that function misbehaves, the defect is in the function, not in whichever caller happened to surface it. Fixing the caller leaves the trap armed for the next one.
This is not only about paths. It applies to any precondition a function depends on but does not enforce: sorted input, canonical case, absolute rather than relative, deduplicated sets, UTC rather than local time, validated identifiers, resolved rather than lazy values.
A useful question when reviewing a signature: if someone passed the un-normalized form tomorrow, would this be loudly wrong or quietly wrong? Quietly wrong means the guarantee belongs inside.
Bypasses are often the source of long-term inconsistency.
Examples:
When possible:
A feature becomes easier to reason about when fewer things are "handled specially."
Add small focused tests for behavior that defines the contract.
Examples of semantic contracts:
Use broad snapshots or regression artifacts after the semantics are nailed down.
Snapshots are useful for regression coverage, but they are weak at explaining why behavior is correct.
If a bug would be hard to understand from a broad diff alone, write a direct test.
Only mark documentation, checklists, or validation items complete when they are:
Treat docs as design intent, not infallible truth.
If you find contradictions:
Documentation should reflect the final ownership model and behavior contracts, not the implementation history.
When working in steps, communicate like this:
Do not narrate every file edit. Do not claim completion until behavior, tests, and docs agree.
Commit when a stable invariant becomes true.
Good commit examples:
Bad commit examples:
Each commit should make the codebase easier to understand, even if the feature is not fully complete yet.
Choose the refactor when it reduces future branching. Choose the common path when special handling would duplicate policy. Choose explicit internal models over implicit combinations of inputs. Choose deletion over compatibility layers when the old layer is redundant. Choose orthogonality over convenience when two concerns are starting to leak into each other.
Ask repeatedly:
A complex task is done when all of these are true:
The standard is not "it passes." The standard is "the next related change will now be easier."
Use this before and during implementation:
Do not build the feature by teaching every layer a new exception; build it by making one clean model true and routing the system through it.
