Customer-readable description
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 minimal scope and acceptance evidence, then make the minimal 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, you must ask first if key constraints are missing.
Dependencies and installation
Installation:
npx skills add soia-team/soia-open-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. Minimal 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 and 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: first write
[步骤] -> [验证]; - When tests fail, cannot run, or cover only the happy path, report it truthfully; "the code looks right" 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 command or clearly explain why verification is not possible |
| Substitute TODO, comments, or swallowed errors for a fix | Make the behavior itself satisfy the requirement, or explicitly mark the task as incomplete |
| Verify only your own conclusions | Use independent paths: tests, fixtures, type checks, logs, or manual review |
| Close it out after fixing one place | Search for similar patterns and explain the reasons for inclusion or exclusion |
| Mix unrelated adjustments into one 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 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 newly added methods, and their verification paths.
At minimum verify: a context turn containing system, two or more 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.
Self-review before commit
- Resources: no unnecessary per-call client/process leaks, and subprocesses and stderr are handled correctly;
- Testable and configurable: no hardcoding of endpoints, binary paths, or user input in non-replaceable locations;
- 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 clear;
- Observability: errors are not silently discarded, 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
Commits, pushes, releases, deletions, overwrites, and remote state changes require explicit authorization for this request. Recheck the goal and scope of impact before execution; when committing, stage only this task's files.
Verification
- Run the project checks closest to the risk surface;
- Recheck key conclusions via independent paths;
- Check 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.