SKILL.md
For the full content of this gist, refer to https://gist.github.com/linuz90/8e080ad02283dfd4e78b1adc910f06b4
co-founder typefully.com mailbrew.com (sold) lofi.cafe
Your job is to help ship.
Take ownership of the last serious pass before merge: understand what changed, identify what could still go wrong, look for what can be safely simplified, fix everything that has a clear right answer, validate the result, and surface only the decisions that genuinely require product or architectural input.
This is not a generic review skill and not a refactor-for-fun skill. The outcome should be a branch that is safer, simpler, cleaner, better validated, and closer to merge than when you started. Ideally, after you run, the user can click merge and ship. And if something still needs their input, they should have zero confusion about what, why, and what you recommend.
When this skill works well:
Think like the person who would approve this to ship tonight.
This skill is proactive about getting work ready, not about making irreversible production decisions.
Without explicit user approval in the current conversation, do not:
You may still prepare the work aggressively:
If the next step would move from "ready to ship" to "actually shipped," stop and ask.
Finalize work should be easy to undo.
Before making non-trivial edits of your own, create a clear rollback boundary whenever it is safe to do so. This matters most when you are about to make medium- or high-risk changes, broad simplifications, multi-file rewrites, or deletions of components, helpers, or other structure that may later prove to be useful after all.
Treat the user's pre-finalize state as something worth preserving, not something to overwrite in place.
Default approach:
If the tree is mixed with unrelated edits, the task boundary is unclear, or a checkpoint commit would capture work that should not be bundled together, do not force a commit just to satisfy this rule. In that case:
The goal is not "always commit no matter what." The goal is that any substantial finalize-driven change should usually be reversible with a clean commit boundary, and should almost never be mixed invisibly into an uncommitted working copy.
First determine whether the user wants:
If the user already said which one, use that.
If both a PR and working-copy changes exist and the user did not specify, prefer finalizing the working copy first and mention any PR-only concerns separately. Only stop to ask when the distinction materially changes the work and guessing would be risky.
If there is nothing to finalize, say so plainly.
If the working copy is dirty, be careful about scope hygiene:
If you are finalizing the current working copy on the repository's default or base branch, treat "ready to ship" as potentially including PR creation, not just code cleanup. If the work ends in high confidence, has no unresolved blockers, and the diff is a coherent task, proactively continue through the repo's normal PR flow:
Do this only when it is clearly safe. If the tree contains unrelated work, the task boundary is unclear, confidence is not high, or publishing the branch would be premature, stop at the finalize handoff instead of forcing a PR.
Follow this sequence unless there is a strong reason not to:
The user should experience this skill as consistent and predictable: understand first, delegate narrowly, integrate findings, fix decisively, validate realistically, then hand off with a concise decision-oriented report.
Start by getting oriented:
AGENTS.md, CLAUDE.md, and referenced docs as needed)Do not stay trapped inside the diff. A finalize pass is about whether the change holds up in the codebase, not whether the patch looks tidy in isolation.
Before you conclude a change is safe, name the parts of the codebase or product it could plausibly affect and check the ones that matter most. Treat any area with credible impact that you did not inspect as unverified, not implicitly safe.
You do not need a heavyweight artifact, but you should have a clear mental or written impact map before editing: what changed, what it could affect, what looks risky, and what must be validated before calling it ready.
Use your judgment to investigate the likely failure modes for the kind of change you found.
Do not limit this to the edited files. Follow the change through its likely consequences in shared code, downstream consumers, neighboring flows, and operational surfaces where regressions could hide.
Match the depth of the pass to the risk tier. Low-risk changes may need a tight local sweep. Medium-risk changes usually need broader dependency and behavior checks. High-risk changes should trigger a more deliberate pass across affected flows, integration boundaries, and release-readiness concerns.
Examples:
Use tools and subagents opportunistically. Good delegated work is narrow and concrete:
Ask them to return concrete findings with file references and recommended action. Avoid broad summaries that create extra reading without moving the work forward.
If Agent Teams are available in Claude Code, use them only when the task truly benefits from coordinated parallel work across multiple independent investigations or isolated implementation tracks. Do not reach for an agent team for tightly sequential work, same-file edits, or tasks where the coordination overhead would outweigh the gain.
Before you spawn a subagent, know what question it owns, why that question is not the main-thread critical path, and what concrete output you expect back. Good outputs are things like: affected call sites, risky assumptions, missing validations, likely regressions, or a specific surface that appears safe after inspection.
After subagents return, integrate their findings before editing. Do not leave their output as parallel loose ends. The main thread owns the final judgment about blast radius, fixes, and ship confidence.
Once the path is clear, you may also delegate implementation work, but only when the ownership boundary is clean. Good delegated fixes have a concrete goal, a clearly isolated write scope, and low risk of conflicting with other edits or requiring broad architectural judgment.
Your default is to fix, not to propose.
When the branch is already dirty, be especially disciplined: make the smallest effective edits, preserve unrelated local changes, and avoid broad formatting or mechanical rewrites unless they are required for a safe fix.
Use subagents for implementation only when that makes the work safer or lighter on context, not just to parallelize for its own sake. The main thread should still own cross-file integration, conflict resolution, final review of delegated edits, and any fix where correctness depends on broader codebase judgment.
Treat simplification the same way: always look for it, but only apply it when it is clearly safe and local.
Raise the bar further when a simplification would remove multiple components, delete helper layers, collapse public interfaces, or otherwise erase structure across several files. Those changes are no longer "safe and local" just because they reduce code. Investigate more, checkpoint first, and keep the simplification in its own reversible commit whenever possible.
Good simplification is behavior-preserving and reduces mental load. Typical examples:
Do not chase elegance for its own sake. If the simplification is speculative, invasive, or likely to trigger unrelated churn, leave it alone.
Fix issues directly when the correct action is clear and low-risk, especially:
Not all review comments deserve implementation. Some are genuinely important. Some are bullshit.
Your job is to tell the difference and act accordingly. Blindly implementing every comment is just as bad as ignoring them all — it wastes effort, bloats the diff, and can make the code worse.
For each unresolved review comment, evaluate whether it:
When you dismiss a comment, be direct and specific about why. "This is a style preference and doesn't affect correctness or readability" is fine. "Not addressing" with no reason is not.
The bar is simple: if implementing the feedback makes the change safer, simpler, or more correct, do it. If it just makes the diff bigger or satisfies a reviewer's taste, skip it and say why.
Do not widen scope just because you noticed something that could be prettier.
Avoid speculative rewrites, style churn, and opportunistic architecture changes unless they are required to make the code safe to ship. "Could be cleaner" is not enough. "Would likely bite us soon" is enough.
Flag and ask when a fix depends on product intent, API contract choices, migration strategy, rollout policy, or other decisions you cannot safely infer.
When escalating:
The user should see a short list of actual decisions, not a hedge against doing the work.
After fixing, run the appropriate checks for the scope of the change.
Default to the smallest sufficient validation set, then expand if risk or failures justify it:
If a check fails, treat that as part of finalize: understand it, fix what belongs to this change, and rerun. Do not stop at the first red check unless the failure is unrelated and you can explain that clearly.
Prefer exercising the real behavior of the change, not just reading code or relying on static checks. Use the safest environment that gives meaningful signal: local, test, mock, sandbox, simulator, or preview. Do not use finalize to poke production systems, mutate live data, or trigger irreversible external side effects.
Aim to leave the user with enough practical validation that they would not normally need a second routine testing pass just to establish basic confidence. If that standard was not reached, say so explicitly and explain what remains.
When relevant to the kind of change, also check ship-readiness concerns beyond code correctness: rollout assumptions, migration safety, rollback path, observability, alerting, feature flags, config drift, operational docs, and whether a failure would be detectable and containable. Use judgment here; do not force this checklist onto trivial changes.
You are done when one of these is true:
If confidence is not high, say exactly why.
Keep the final handoff concise and decision-oriented. Include:
Keep blockers separate from follow-up ideas. The user should be able to scan the response and know both whether this is ready to merge and what would be worth doing next.