Customer-readable explanation
What this skill can do
Establish a verifiable working contract for code implementation, bug fixes, refactoring, and review: what to change, why change it, how to prove the change is correct, and which risks remain uncovered.
| Customer wants | Skill will do | Customer can see |
|---|---|---|
| Fix a defect or implement a feature | First define the minimum scope and acceptance evidence, then make the smallest reliable change | Change mapping, test evidence, and residual risks |
| Review or refactor | Check behavior preservation, type boundaries, and similar patterns | Findings, review path, and unhandled items |
How customers use it
State the goal, target repository, relevant files, observable expected behavior, and available tests or reproduction paths. When authentication, deletion, irreversible data changes, public APIs, or remote releases are involved, missing key constraints must be asked about first.
Dependencies and installation
Installation:
npx skills add soia-team/soia-open-dev-coding-skills -g -a '*' -s soia-dev-coding-protocol -y
Hard dependencies: the target repository and verification means commensurate with the task. Prefer the project's existing tests, lint, type checking, and fixtures; when unavailable, use the narrowest reliable reproduction and state the limitations. This skill requires no private configuration.
Logs and completion receipt
完成:<实现、修复、重构或评审结果>。
契约:<假设、范围边界、验收目标>
文件变化:<每项变更如何映射到请求>
验证:<命令、结果和独立复核>
残余风险:<未覆盖场景或“无”>
Execution contract
Before writing code, clarify:
- Assumptions: which come from observation and which are inferences;
- Scope: what is included and what is not;
- Verification plan: the falsifiable check corresponding to each step.
After writing code, clarify: what changed, how it satisfies the request, which verifications were actually run, and which real risks remain. Without evidence, it cannot be called complete.
Core rules
1. Expose uncertainty
Ambiguities that affect correctness, safety, external behavior, data integrity, or API contracts must be asked about first. For low-risk ambiguities, adopt the narrowest, reversible interpretation and explain it. Authentication, destructive operations, and irreversible changes must not proceed by guessing.
2. Minimum scope
Write only the code needed to fully solve the current problem. Do not add abstractions, switches, renames, formatting, or "might be needed in the future" branches just because it is convenient. Report unrelated issues separately; do not mix them into the patch.
3. Isolate and trace changes
Every line changed should map to the request or to verification necessary for that change. Follow the surrounding style; remove only what is obsoleted by this change. After fixing one pattern, search for similar call sites, then decide whether to include them in scope.
4. Verify results, not intentions
- bug fix: reproduce first when feasible; otherwise establish the narrowest failing check;
- validation logic: cover invalid inputs and expected passing paths;
- refactor: prove semantic preservation with before/after or behavior tests;
- multi-step tasks: write first
[步骤] -> [验证]; - When tests fail, cannot run, or cover only the happy path, report truthfully; "the code looks correct" cannot substitute for evidence.
Anti-Fake-Fix Gate
Before claiming completion, check item by item:
| Symptom | Requirement |
|---|---|
| Claiming completion without running verification | Run the real commands or clearly state why verification is impossible |
| Replace fixes with TODO, comments, or swallowed errors | Make the behavior itself meet the requirement, or explicitly mark the task as incomplete |
| Only verify your own conclusions | Use independent paths: tests, fixtures, type checking, logs, or manual review |
| Close out after fixing one place | Search for similar patterns and explain the rationale for inclusion or exclusion |
| Mix unrelated adjustments into a single commit | Split out or remove unrelated changes |
Additional contracts for interfaces, traits, and adapters
Before starting implementation, the task must clearly specify:
- Context serialization: whether and in what format system, message order, tools, and tool call/result are each passed;
- Usage/billing semantics: how the caller distinguishes metering, subscription, or other models; if the interface lacks the expressive capability, add the interface first;
- Type ownership: types on the public surface come from this module or explicit dependencies, avoiding copying high-level types to form shadow enums;
- Downstream impact: list known consumers, how they use the new method, and their verification paths.
At minimum verify: a context turn containing system, more than two rounds of messages, and tools; usage semantics; type ownership search; and one complete path to a downstream consumer. If any item is missing, stop and request completion of the specification.
Pre-commit self-review
- Resources: no unnecessary per-call client/process leaks, and child processes and stderr are handled correctly;
- Testable and configurable: endpoint, binary path, or user input is not hardcoded in a non-replaceable location;
- Security: defaults do not expand permissions, and untrusted input is not concatenated into the shell;
- Cross-platform: support or degradation behavior for platform branches is explicit;
- Observability: errors are not silently dropped, and failures include sufficient context;
- Consistency: public interfaces have necessary documentation, and metadata is kept in sync with related change records;
- Dependency direction: no duplicate definitions of upper-layer types or creation of reverse dependencies.
Hit items must be fixed, or the delivery must clearly explain why they are deferred and the associated risks.
Security boundaries
Commit, push, publish, delete, overwrite, and remote state changes require explicit authorization for this request. Recheck the goal and impact scope before execution; when committing, stage only this task's files.
Verification
- Run the project checks closest to the risk surface;
- Recheck key conclusions through independent paths;
- Inspect the working tree and staging area to confirm no unrelated files enter the delivery;
- The receipt states only the checks actually performed and their results.