implementation-discipline
Minimal implementation workflow for plan-driven coding. Use when preparing a small implementation slice, applying requirements-first coding discipline, verifying that new code delegates instead of duplicating behavior, propagating a qualifying sentence to several sites, or swapping a term across a migration table. DO NOT USE FOR: test authoring strategy (use test-driven-development) or refactoring-only passes (use refactoring-methodology)
- License 许可
- MIT
- 最近更新
- 2026-08-16
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- implementation-discipline
- description
- Minimal implementation workflow for plan-driven coding. Use when preparing a small implementation slice, applying requirements-first coding discipline, verifying that new code delegates instead of duplicating behavior, propagating a qualifying sentence to several sites, or swapping a term across a migration table. DO NOT USE FOR: test authoring strategy (use test-driven-development) or refactoring-only passes (use refactoring-methodology)
02 资源文件 4
03 SKILL.md 正文
<!-- platform-assumptions: markdown skill guidance for VS Code custom agents in Agent Orchestra; assumes implementation work is plan-driven and validated in-repo. --> <!-- markdownlint-disable-file MD041 MD003 -->
Implementation Discipline
Reusable implementation methodology for small, requirement-driven code changes.
When to Use
- When implementing a bounded plan step or failing behavior slice
- When deciding how much code to add and how to keep the implementation minimal
- When checking whether new code should delegate to existing logic rather than duplicate it
- When validating implementation quality before handing off review or follow-up testing
Purpose
Implement only what the requirements demand, with clear delegation boundaries and immediate validation. The goal is not to make tests green by any means necessary; it is to land the smallest correct implementation that satisfies the actual requirement.
Composite References
- references/implementation-exhibits.md: the incident detail behind § Implementation Lenses — the propagation and migration failures each lens was extracted from, with the counts that made them visible
Pre-Implementation Review
- Review the plan, design context, and local architecture constraints.
- Confirm the intended change belongs in the current layer.
- Outline the smallest implementation slice and likely files to touch.
- Apply the replaceability test: if switching UI technology would change the code, it belongs outside core logic.
Implementation Standards
- Do not add speculative features, helper methods, or abstractions without a current requirement
- Use straightforward names and keep control flow easy to inspect
- Prefer minimal changes over broad rewrites
- Extract helpers when complexity limits or readability clearly require it
- Follow repo architecture and file-size rules before adding new structure
- Leave adjacent cleanup and follow-up ideas out of the implementation unless they are required for correctness
Requirements Verification
After implementing a slice, verify:
- New components are wired into production code, not only tests.
- Expected integration points are actually connected.
- The implementation satisfies the design requirements and acceptance criteria.
- Any JSON output created or edited is parseable and preserves required array typing.
If a requirement is missing from tests but clearly part of the requested behavior, implement it anyway and call out the missing coverage.
Bad Test Detection
Stop implementation immediately when a failing or newly added test is likely wrong instead of exposing a product gap.
Treat these as stop conditions:
- The test appears to have a bug or incorrect expectation
- The test checks implementation details rather than behavior
- The test assertions do not match the documented requirements
- The test setup is incomplete or creates invalid state
- Multiple tests fail for the same likely test-side root cause
Do not modify the tests yourself, work around the test with distorted implementation, or spend time debugging test logic in the implementation lane.
Instead:
- Stop immediately
- Document the specific problem
- Return a clear report so the orchestrator can route the issue to Test-Writer
Use this report shape:
? BAD TEST DETECTED - STOPPING
**File**: [test file path]
**Test**: [test name]
**Problem**: [clear description of what is wrong]
**Evidence**: [why the test is wrong, rather than the implementation]
Returning to orchestrator for redirection to Test-Writer.
```text
```
Why this matters: implementing against a broken test wastes time and pushes the code away from the real requirement.
Halt-Return Conditions
Halt and return without completing the slice when either of these implement-code-specific conditions is met:
- Scope violation — the slice requires touching files unrelated to the dispatched requirement. Halt with reason
scope-violation. - Simplicity violation — the implementation would require a new architectural seam, substantial refactor, or cross-layer dependency not called for by the plan. Halt with reason
simplicity-violation.
For the Halt-Return shape and the full reason enum, see agents/Senior-Engineer.agent.md § ## Halt-Return Contract — that section is the single authoritative source.
Implementation Requirements Verification
Passing tests is not sufficient. Verify the shipped behavior against the requirement before handing work off.
After implementation, confirm:
- New components are wired into production code, not only tests.
- Expected integration points are actually connected.
- The implementation satisfies the design requirements and acceptance criteria.
- Any JSON output created or edited is parseable and preserves required array typing.
- For generated user-facing explanatory text spanning multiple root causes (a Note, warning, or error message covering more than one "why did this happen" case): verify each sub-case is named distinctly rather than conflated with a differently-caused sub-case under shared wording, and that it cross-references any companion doc a maintainer needs to act on it correctly.
For JSON changes:
- Prefer structured serializers over manual quoting.
- Validate the final output with the language's JSON parser.
- When array-typed fields are present, verify that single-element writes preserve array identity.
- In PowerShell, use
return , @(...)orWrite-Output -NoEnumeratewhen array identity must survive output.
If you find a requirement gap that the current tests do not cover:
- Implement the missing functionality anyway.
- Flag the missing coverage explicitly in the handoff.
Use this report shape:
⚠️ MISSING TEST COVERAGE:
- [missing behavior that was implemented but not covered]
- Recommend adding integration or behavior coverage for the missing requirement
Delegation Instead Of Duplication
When a new file or class needs logic that already exists:
- Search for the existing formula, mapping, or validation first.
- Inject the dependency and call it instead of copying behavior.
- Use composition, strategies, or pipelines rather than parallel duplicate implementations.
Load software-architecture before extractions or new structural seams that affect layering or dependency direction.
Verification Flow
- Make the bounded implementation change.
- Run the cheapest relevant validation for that slice.
- Repair local defects before widening scope.
- Only hand off once the implementation and validation agree with the requirement.
Documentation And Markdown Hygiene
When implementation work edits permanent markdown files, run:
npx markdownlint-cli2 --fix "**/*.md" "!node_modules" "!.copilot-tracking" "!.copilot-tracking-archive"
Then run the repository validation command required by the current task.
Related Guidance
- Load
systematic-debuggingwhen the root cause is unclear - Load
frontend-designfor intentional UI work - Load
parallel-executionwhen the current step explicitly runs in parallel mode
Implementation Lenses
Authoritative source: which lessons are promoted here, what anchor each one lives at, and the trigger text that has to reach a reader are recorded in
Documents/Planning/lesson-promotion-manifest.json..github/scripts/Tests/lesson-promotion-manifest.Tests.ps1is what stops this section and that manifest drifting apart, and it is the suite a red comes from. Renaming a heading below is a migration, not a regression — update that lesson'sanchorin the manifest in the same commit as the rename. A red naming an anchor you just renamed is reporting a manifest row left behind, not a lost lens.
Two ways an edit that is correct in one file lands false in the next. Both bite during the mechanical half of a change — the propagation, the sweep, the rename — which is exactly where attention is lowest. Incident detail sits in references/implementation-exhibits.md.
When you are propagating a claim across sites, or swapping a term across a migration
When one qualifying claim is propagated to many sites, the boilerplate copies are where it turns false
A remedy that fixes an over-broad claim by copying a qualifying sentence to every affected file usually reproduces its own defect one level down: the qualifier states a property that holds at some of the sites, and uniform phrasing is precisely what erases the fact that decided where. The discriminator is sharp and worth checking for directly — every variant hand-written for its site tends to be correct, and every boilerplate copy tends to be wrong, because writing per site forces you to name the site's own case. So before propagating any qualifying sentence to N sites: list the sites, ask what makes this true here, and confirm that property actually holds there. If the answer differs, split the sentence into the universal part and the conditional part, state the conditioning variable as a table in one home, and have each site say which case it is in. Watch the direction of the error too — the copy is most harmful at the site the analysis itself flagged as the sharp one. Exhibit: references/implementation-exhibits.md § A clause that was false at 11 of 15 sites.
Swapping the subject noun leaves the old predicate, and the sentence lands false
When a migration table says "replace term A with term B in this sentence", the deliverable is a sentence that reads true — not a sentence with B in it. The failure is silent because the noun is auditable by grep and the predicate is auditable only by reading, so a completion check built on token counting or occurrence counts is structurally blind to it, and a full review panel can pass a sentence that was false the moment it landed. For each migrated sentence, read the predicate against the artifact it now describes, not against the artifact it used to describe. Pair any verbatim-quoting migration table with a per-sentence read, and treat a prior enumeration of the affected sites as a floor rather than a set — the same class produces enumerations that grow on each recount. Exhibit: references/implementation-exhibits.md § A migrated sentence that was false on landing.
Gotchas
| Trigger | Gotcha | Fix |
|---|---|---|
| Coding directly to satisfy a narrow assertion | Tests pass while the actual requirement or wiring remains missing | Re-check production wiring and design requirements before handoff |
| Trigger | Gotcha | Fix |
|---|---|---|
| Copying logic into a new helper or class | The change creates a second source of truth that drifts later | Search first, inject the existing dependency, and delegate |
Frame Ports Filled By This Skill
| Port | Work adapter | Auto-N/A adapter | Explicit-skip adapter |
|---|---|---|---|
implement-code |
agents/Code-Smith.agent.md; adapters/implement-code-adapter.md | adapters/implement-code-auto-na-adapter.md | adapters/implement-code-explicit-skip-adapter.md |
04 同仓库更多 Skills
webapp-testing
Playwright end-to-end testing guidance for web apps, with practical patterns and setup steps. Use when creating or improving browser-based E2E coverage, test stability, and CI execution. DO NOT USE FOR: React component tests (use ui-testing), canvas game interaction (use browser-canvas-testing), TDD workflow (use test-driven-development), debugging failures (use systematic-debugging), or randomized property tests (use property-based-testing).
verification-before-completion
Evidence-based verification checklist before marking work complete. Use before PRs, releases, marking tickets done, or any "I'm finished" declaration; also when naming a baseline commit for a differential suite claim, when designing a mutation campaign or red-run evidence, when making an absence claim, a universal claim, or a one-time demonstration offered as a standing guarantee, when attributing a measurement or claiming a sweep or verification loop is complete, and when stating what a check or a CI suite will do about a change. DO NOT USE FOR: post-merge cleanup or archival (use post-pr-review) or processing GitHub review comments (use code-review-intake).
validation-methodology
Reusable validation and review methodology for staged validation, failure triage, and prosecution-depth setup. Use when running validation ladders, triaging failures, or executing adversarial review passes. DO NOT USE FOR: CE Gate orchestration, specialist dispatch ownership, or step execution flow (keep those in Code-Conductor).
upstream-onboarding
Shared opening-phase protocol for upstream agents (Experience-Owner, Solution-Designer, Issue-Planner) and Code-Conductor when invoked on an existing GitHub issue. Renders a scaled context brief and runs a standards check on inherited work at each phase boundary. Use when a user-invocable agent receives a request referencing an existing GitHub issue and must load solution-authoring and upstream-onboarding at the opening phase. DO NOT USE FOR: subagent dispatches (which already operate within an assessed session context); post-merge review (use post-pr-review); research or non-tree subagents.
ui-testing
Resilient React component testing strategies focusing on user behavior. Use when writing or reviewing component-level React tests, fixing flaky component tests, or establishing React testing patterns. DO NOT USE FOR: Playwright E2E tests (use webapp-testing), canvas game interaction (use browser-canvas-testing), TDD workflow (use test-driven-development), debugging failures (use systematic-debugging), UI component design (use frontend-design), or randomized property tests (use property-based-testing).
ui-iteration
Reusable screenshot-driven UI polish workflow for iterative visual refinement. Use when improving layout, hierarchy, spacing, feedback, or Tailwind-based presentation through repeated review-and-adjust passes. DO NOT USE FOR: functional bug fixing, accessibility-only audits, or major redesign strategy work (use Code-Smith or frontend-design).