1
---
2
name: implementation-workflow
3
description: Implement code changes with disciplined scope control, repository-state preservation, relevant verification, and concern-scoped commits. Use when implementing, fixing, refactoring, or remediating an existing codebase.
4
---
5
6
# Implementation Workflow
7
8
Implement the requested change safely, minimally, and in a reviewable form.
9
10
## Scope and priority
11
12
Follow the current task, applicable repository instructions such as `AGENTS.md`, and established project conventions.
13
14
Do not expand scope merely because adjacent improvements are possible.
15
16
This skill governs implementation and remediation. Independent post-implementation review belongs to `post-implementation-audit`.
17
18
## 1. Inspect before changing
19
20
Before editing:
21
22
- understand the requested behavior and acceptance criteria;
23
- inspect the relevant existing implementation;
24
- inspect repository status when Git is available;
25
- identify pre-existing modified, staged, deleted, or untracked files.
26
27
Treat unrelated existing changes as protected.
28
29
Do not overwrite, discard, normalize, or accidentally include unrelated work.
30
31
## 2. Decide whether a plan is needed
32
33
Proceed directly when the task is small, localized, low-risk, and sufficiently clear.
34
35
For substantial work, use an implementation plan first unless an approved plan already exists.
36
37
Work is substantial when it involves meaningful architectural uncertainty, multiple interacting components, migrations, public contracts, broad behavioral changes, or significant security/reliability risk.
38
39
When a new plan is required, produce the plan and stop before modifying the repository so it can be reviewed.
40
41
Do not create ceremonial plans for trivial work.
42
43
## 3. Implement narrowly
44
45
Once implementation is authorized:
46
47
- make the smallest coherent change that satisfies the task;
48
- preserve existing architecture and conventions unless the task intentionally changes them;
49
- prefer existing mechanisms over unnecessary parallel abstractions;
50
- avoid unrelated refactoring, cleanup, renaming, formatting churn, dependency changes, or speculative improvements;
51
- preserve unrelated changes in files that must also be edited.
52
53
Do not weaken tests, validation, error handling, or existing guarantees merely to make the new implementation pass.
54
55
## 4. Preserve repository state
56
57
Do not discard existing work to obtain a clean repository.
58
59
Unless explicitly required and authorized, do not use destructive or history-rewriting operations such as:
60
61
- `git reset`
62
- `git restore`
63
- `git stash`
64
- `git clean`
65
- rebase
66
- amend
67
- squash
68
- other history rewriting
69
70
Work around unrelated dirty state instead of erasing it.
71
72
## 5. Verify the implementation
73
74
Use the smallest relevant verification first, then expand when scope or risk warrants it.
75
76
Relevant verification may include targeted tests, static analysis, linting, type checking, builds, or repository-specific checks.
77
78
Add or update tests when needed to prove changed behavior.
79
80
Test meaningful behavior and failure paths rather than merely mirroring implementation details.
81
82
Never claim verification that was not actually performed.
83
84
If relevant verification cannot run, report the limitation rather than assuming success.
85
86
## 6. Create commits only when authorized
87
88
Create commits only when explicitly authorized by the current task or applicable repository instructions.
89
90
When commits are authorized:
91
92
- each commit must represent one coherent concern;
93
- keep unrelated implementation, cleanup, formatting, documentation, and refactoring concerns separate unless inseparable;
94
- keep commits independently understandable, reviewable, and reasonably revertible;
95
- use meaningful commit messages.
96
97
Before each commit:
98
99
1. inspect repository state;
100
2. identify exactly which changes belong to the concern;
101
3. stage only those changes;
102
4. inspect the staged diff;
103
5. commit only after confirming its scope.
104
105
Prefer explicit file or hunk staging.
106
107
Do not use broad staging such as `git add .` when it could capture unrelated changes.
108
109
Do not rewrite existing commits unless explicitly requested.
110
111
## 7. Finish and hand off
112
113
Before declaring implementation complete:
114
115
- confirm the requested behavior and acceptance criteria are addressed;
116
- run relevant final verification;
117
- inspect the final diff for accidental or unrelated changes;
118
- report unresolved limitations honestly.
119
120
For substantial implementations, hand off to `post-implementation-audit` after implementation changes stop.
121
122
If the audit reports findings:
123
124
1. return to an implementation/remediation phase;
125
2. fix only supported findings with the smallest coherent change;
126
3. verify the remediation;
127
4. run `post-implementation-audit` again.
128
129
Repeat until the audit is `CLEAR` or an unresolved limitation is explicitly reported.
130
131
Small, localized changes need an independent audit only when the task, repository instructions, or risk justifies one.
132
133
## Output
134
135
At completion, concisely report:
136
137
- what changed;
138
- important implementation decisions;
139
- verification actually performed;
140
- material limitations or unresolved issues;
141
- commits created, if any.
142
143
Do not reproduce this workflow as a checklist in the final response.