code-simplification

Name: code-simplification
Author: tranhieutt

69stars41forks

How to install code-simplification?

tranhieutt/software_development_department/code-simplification

$npx -y skills add tranhieutt/software_development_department --skill code-simplification

Installs into the current project.

Summary

Simplifies working code while preserving exact behavior. Use after tests pass, during review feedback, or when code is harder to read, maintain, or verify than it needs to be without changing product behavior.

Files · 1

View on GitHub

SKILL.md

1	# Code Simplification
2
3	## Purpose
4
5	`code-simplification` reduces code complexity while preserving exact behavior.
6	It is not a feature workflow, not a bug fix workflow, and not permission for
7	drive-by refactors.
8
9	The goal is code that is easier to read, review, test, and maintain with the
10	smallest safe diff.
11
12	```text
13	Same behavior.
14	Less cognitive load.
15	Fresh verification evidence.
16	```
17
18	Prefer simplifications that deepen modules instead of flattening behavior across
19	callers. A small interface hiding real complexity is valuable; a wrapper that
20	only moves complexity around is not.
21
22	## When to Use
23
24	Use this workflow when:
25
26	- The implementation is working and relevant tests pass.
27	- Code review flags readability, complexity, naming, duplication, or avoidable
28	abstraction.
29	- The user asks to simplify, clean up, reduce complexity, or refactor without
30	changing behavior.
31	- A recently changed area has nested logic, long functions, unclear names, or
32	repeated conditionals that make future changes risky.
33
34	Do not use this workflow when:
35
36	- Behavior must change. Use `spec-driven-development`, `test-driven-development`,
37	or `spec-evolution`.
38	- The code is not understood well enough to preserve behavior.
39	- There is no verification path.
40	- The cleanup would touch unrelated files.
41	- The work is a hotfix where cleanup is not required for the fix.
42
43	## Position in SDD
44
45	Preferred placement:
46
47	```text
48	test-driven-development -> code-simplification -> verification-before-completion
49	```
50
51	Review feedback placement:
52
53	```text
54	code-review -> receiving-code-review -> code-simplification
55	-> verification-before-completion
56	```
57
58	Technical-debt placement:
59
60	```text
61	tech-debt identifies issue -> user approves focused cleanup
62	-> code-simplification
63	```
64
65	If a simplification requires changing externally visible behavior, API shape,
66	data model, error behavior, timing, permissions, or user flow, stop and route to
67	`spec-evolution`.
68
69	## Preconditions
70
71	Before editing, all must be true:
72
73	- [ ] Target scope is explicit: file(s), function(s), or review finding.
74	- [ ] Intended behavior is known.
75	- [ ] Relevant tests, build, lint, typecheck, or manual verification are known.
76	- [ ] The current worktree state has been checked.
77	- [ ] The simplification is within the approved scope.
78
79	State the gate before edits:
80
81	```text
82	Pre-code gate: Fast satisfied for behavior-preserving simplification of <scope>; verification: <command/check>.
83	```
84
85	For cleanup attached to an approved task:
86
87	```text
88	Pre-code gate: Plan satisfied by approved Task N; simplification scope: <scope>; verification: <command/check>.
89	```
90
91	## Workflow
92
93	### 1. Understand Before Touching
94
95	Read the smallest necessary context and answer:
96
97	- What does this code do?
98	- Who calls it, and what does it call?
99	- What inputs, outputs, errors, side effects, and ordering matter?
100	- Which tests or checks prove behavior?
101	- Does git history or nearby code explain why it exists?
102
103	If you cannot answer, do not simplify yet. Gather context or ask.
104
105	### 2. Identify Concrete Simplification Targets
106
107	Only act on specific signals:
108
109	\| Signal \| Typical simplification \|
110	\| --- \| --- \|
111	\| Deep nesting \| Guard clauses or named predicates \|
112	\| Long function with mixed responsibilities \| Extract focused helper(s) \|
113	\| Nested ternaries \| Readable conditional or lookup \|
114	\| Boolean flag parameters \| Options object or separate functions when warranted \|
115	\| Repeated conditionals \| Named predicate \|
116	\| Generic names \| Names that describe domain meaning \|
117	\| Duplicate logic \| Shared helper, if it reduces real duplication \|
118	\| Unused wrapper \| Inline only if the wrapper has no semantic value \|
119	\| Comments explaining obvious "what" \| Remove or replace with clearer code \|
120
121	Use the deletion test on wrappers, helpers, and extracted modules:
122
123	- If deleting the abstraction would force several callers to re-learn hard
124	behavior, it is probably earning its keep.
125	- If deleting it mostly removes indirection and does not spread meaningful
126	complexity, it is probably shallow.
127
128	Prefer deeper modules with clearer seams over helper sprawl.
129
130	Keep comments that explain why, tradeoffs, gotchas, or external constraints.
131
132	### 3. Apply One Safe Change at a Time
133
134	For each simplification:
135
136	1. Make the smallest behavior-preserving edit.
137	2. Run the relevant verification if cheap and available.
138	3. If verification fails, revert or diagnose before continuing.
139	4. Sto

People who liked this also viewed

6 picks

Type

code-simplification

69stars41forks

View on GitHub

How to install code-simplification?

tranhieutt/software_development_department/code-simplification

$npx -y skills add tranhieutt/software_development_department --skill code-simplification

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Code Simplification
2
3	## Purpose
4
5	`code-simplification` reduces code complexity while preserving exact behavior.
6	It is not a feature workflow, not a bug fix workflow, and not permission for
7	drive-by refactors.
8
9	The goal is code that is easier to read, review, test, and maintain with the
10	smallest safe diff.
11
12	```text
13	Same behavior.
14	Less cognitive load.
15	Fresh verification evidence.
16	```
17
18	Prefer simplifications that deepen modules instead of flattening behavior across
19	callers. A small interface hiding real complexity is valuable; a wrapper that
20	only moves complexity around is not.
21
22	## When to Use
23
24	Use this workflow when:
25
26	- The implementation is working and relevant tests pass.
27	- Code review flags readability, complexity, naming, duplication, or avoidable
28	abstraction.
29	- The user asks to simplify, clean up, reduce complexity, or refactor without
30	changing behavior.
31	- A recently changed area has nested logic, long functions, unclear names, or
32	repeated conditionals that make future changes risky.
33
34	Do not use this workflow when:
35
36	- Behavior must change. Use `spec-driven-development`, `test-driven-development`,
37	or `spec-evolution`.
38	- The code is not understood well enough to preserve behavior.
39	- There is no verification path.
40	- The cleanup would touch unrelated files.
41	- The work is a hotfix where cleanup is not required for the fix.
42
43	## Position in SDD
44
45	Preferred placement:
46
47	```text
48	test-driven-development -> code-simplification -> verification-before-completion
49	```
50
51	Review feedback placement:
52
53	```text
54	code-review -> receiving-code-review -> code-simplification
55	-> verification-before-completion
56	```
57
58	Technical-debt placement:
59
60	```text
61	tech-debt identifies issue -> user approves focused cleanup
62	-> code-simplification
63	```
64
65	If a simplification requires changing externally visible behavior, API shape,
66	data model, error behavior, timing, permissions, or user flow, stop and route to
67	`spec-evolution`.
68
69	## Preconditions
70
71	Before editing, all must be true:
72
73	- [ ] Target scope is explicit: file(s), function(s), or review finding.
74	- [ ] Intended behavior is known.
75	- [ ] Relevant tests, build, lint, typecheck, or manual verification are known.
76	- [ ] The current worktree state has been checked.
77	- [ ] The simplification is within the approved scope.
78
79	State the gate before edits:
80
81	```text
82	Pre-code gate: Fast satisfied for behavior-preserving simplification of <scope>; verification: <command/check>.
83	```
84
85	For cleanup attached to an approved task:
86
87	```text
88	Pre-code gate: Plan satisfied by approved Task N; simplification scope: <scope>; verification: <command/check>.
89	```
90
91	## Workflow
92
93	### 1. Understand Before Touching
94
95	Read the smallest necessary context and answer:
96
97	- What does this code do?
98	- Who calls it, and what does it call?
99	- What inputs, outputs, errors, side effects, and ordering matter?
100	- Which tests or checks prove behavior?
101	- Does git history or nearby code explain why it exists?
102
103	If you cannot answer, do not simplify yet. Gather context or ask.
104
105	### 2. Identify Concrete Simplification Targets
106
107	Only act on specific signals:
108
109	\| Signal \| Typical simplification \|
110	\| --- \| --- \|
111	\| Deep nesting \| Guard clauses or named predicates \|
112	\| Long function with mixed responsibilities \| Extract focused helper(s) \|
113	\| Nested ternaries \| Readable conditional or lookup \|
114	\| Boolean flag parameters \| Options object or separate functions when warranted \|
115	\| Repeated conditionals \| Named predicate \|
116	\| Generic names \| Names that describe domain meaning \|
117	\| Duplicate logic \| Shared helper, if it reduces real duplication \|
118	\| Unused wrapper \| Inline only if the wrapper has no semantic value \|
119	\| Comments explaining obvious "what" \| Remove or replace with clearer code \|
120
121	Use the deletion test on wrappers, helpers, and extracted modules:
122
123	- If deleting the abstraction would force several callers to re-learn hard
124	behavior, it is probably earning its keep.
125	- If deleting it mostly removes indirection and does not spread meaningful
126	complexity, it is probably shallow.
127
128	Prefer deeper modules with clearer seams over helper sprawl.
129
130	Keep comments that explain why, tradeoffs, gotchas, or external constraints.
131
132	### 3. Apply One Safe Change at a Time
133
134	For each simplification:
135
136	1. Make the smallest behavior-preserving edit.
137	2. Run the relevant verification if cheap and available.
138	3. If verification fails, revert or diagnose before continuing.
139	4. Sto

People who liked this also viewed

6 picks

Type