code-simplification

Name: code-simplification
Author: jmxt3

32stars3forks

How to install code-simplification?

jmxt3/gitscape.ai/code-simplification

$npx -y skills add jmxt3/gitscape.ai --skill code-simplification

Installs into the current project.

Summary

Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.

Files · 1

View on GitHub

SKILL.md

1	# Code Simplification
2
3	## Overview
4
5	Reduce complexity while preserving exact behavior. The goal is code that a new engineer can read and understand without asking the author questions. Simplification is not optimization — do not change performance characteristics unless that is the explicit goal.
6
7	## When to Use
8
9	- Code works but is harder to read than it should be
10	- A function is doing more than one thing
11	- Nested conditionals make the control flow hard to follow
12	- Variable names are generic (`data`, `result`, `temp`)
13	- The same logic appears in multiple places
14	- A reviewer needed to ask what the code does
15
16	When NOT to use: Code that is intentionally complex for performance reasons (document with a comment instead of simplifying).
17
18	## The Chesterton's Fence Rule
19
20	> "Don't remove a fence you don't understand."
21
22	Before simplifying any code, answer: why was it written this way? If you can't answer that, you risk removing a safeguard. Read the git history, grep for related tests, and understand the intent before changing anything.
23
24	## The Simplification Process
25
26	### Step 1: Understand Before Touching
27
28	- Read the function end-to-end
29	- Read its callers — what do they expect?
30	- Read its tests — what behavior is verified?
31	- Check git history: `git log -p -- path/to/file.py`
32	- Do not change anything yet
33
34	### Step 2: Cover First
35
36	If the code lacks tests, add tests before simplifying. You need a safety net:
37
38	```python
39	def test_generate_skill_name_sanitizes_input():
40	assert generate_skill_name("my repo") == "my-repo"
41	assert generate_skill_name("My Repo!") == "my-repo"
42	assert generate_skill_name(" spaces ") == "spaces"
43	```
44
45	Run them, confirm they pass. Now you can simplify safely.
46
47	### Step 3: Apply Simplifications Incrementally
48
49	Apply one simplification at a time, running tests after each:
50
51	#### Deep Nesting → Guard Clauses
52
53	```python
54	# BAD: Pyramid of doom
55	def process_skill(skill):
56	if skill is not None:
57	if skill.get("name"):
58	if len(skill["name"]) > 0:
59	return skill["name"].lower()
60	return None
61	return None
62
63	# GOOD: Guard clauses
64	def process_skill(skill):
65	if not skill:
66	return None
67	if not skill.get("name"):
68	return None
69	return skill["name"].lower()
70	```
71
72	#### Long Functions → Extracted Helpers
73
74	```python
75	# BAD: One function doing three jobs
76	def export_skill(repo: str) -> bytes:
77	# Fetch files
78	files = []
79	for branch in ["main", "master"]:
80	try:
81	contents = github_client.get_contents(repo, branch)
82	files = contents
83	break
84	except Exception:
85	continue
86
87	# Filter relevant files
88	relevant = [f for f in files if f.path.endswith((".md", ".py", ".ts"))]
89
90	# Build zip
91	buf = io.BytesIO()
92	with zipfile.ZipFile(buf, "w") as zf:
93	for f in relevant:
94	zf.writestr(f.path, f.decoded_content)
95	return buf.getvalue()
96
97	# GOOD: Each function does one thing
98	def export_skill(repo: str) -> bytes:
99	files = fetch_repo_files(repo)
100	relevant = filter_skill_files(files)
101	return build_zip(relevant)
102
103	def fetch_repo_files(repo: str) -> list:
104	for branch in ["main", "master"]:
105	try:
106	return github_client.get_contents(repo, branch)
107	except Exception:
108	continue
109	return []
110
111	def filter_skill_files(files: list) -> list:
112	return [f for f in files if f.path.endswith((".md", ".py", ".ts"))]
113
114	def build_zip(files: list) -> bytes:
115	buf = io.BytesIO()
116	with zipfile.ZipFile(buf, "w") as zf:
117	for f in files:
118	zf.writestr(f.path, f.decoded_content)
119	return buf.getvalue()
120	```
121
122	#### Generic Names → Descriptive Names
123
124	```python
125	# BAD
126	def process(d, r):
127	result = []
128	for item in d:
129	if item["type"] == r:
130	result.append(item)
131	return result
132
133	# GOOD
134	def filter_files_by_type(files: list[dict], file_type: str) -> list[dict]:
135	return [f for f in files if f["type"] == file_type]
136	```
137
138	#### Duplicated Logic → Shared Functions
139
140	```python
141	# BAD: Same validation in three places
142	def create_skill(name: str):
143	if not name or len(name) > 100:
144	raise ValueError("Invalid name")
145	...
146
147	def update_skill(name: str):
148	if not name or len(name) > 100:
149	raise ValueError("Invalid name")
150	...
151
152	# GOOD
153	def validate_skill_name(name: str) -> None:
154	if not name or len(name) > 100:
155	raise ValueError("Skill name must be 1-100 characters")
156
157	def create_skill(name: str):
158	validate_skill_name(name)
159	...
160	```
161
162	### Step 4: Verify Nothing Changed
163
164	Run the full test suite after each simplification:
165
166	```bash
167	pytest tests/ -v
168	```
169
170	If any test fails, revert that specifi

People who liked this also viewed

6 picks

Type

code-simplification

32stars3forks

View on GitHub

How to install code-simplification?

jmxt3/gitscape.ai/code-simplification

$npx -y skills add jmxt3/gitscape.ai --skill code-simplification

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Code Simplification
2
3	## Overview
4
5	Reduce complexity while preserving exact behavior. The goal is code that a new engineer can read and understand without asking the author questions. Simplification is not optimization — do not change performance characteristics unless that is the explicit goal.
6
7	## When to Use
8
9	- Code works but is harder to read than it should be
10	- A function is doing more than one thing
11	- Nested conditionals make the control flow hard to follow
12	- Variable names are generic (`data`, `result`, `temp`)
13	- The same logic appears in multiple places
14	- A reviewer needed to ask what the code does
15
16	When NOT to use: Code that is intentionally complex for performance reasons (document with a comment instead of simplifying).
17
18	## The Chesterton's Fence Rule
19
20	> "Don't remove a fence you don't understand."
21
22	Before simplifying any code, answer: why was it written this way? If you can't answer that, you risk removing a safeguard. Read the git history, grep for related tests, and understand the intent before changing anything.
23
24	## The Simplification Process
25
26	### Step 1: Understand Before Touching
27
28	- Read the function end-to-end
29	- Read its callers — what do they expect?
30	- Read its tests — what behavior is verified?
31	- Check git history: `git log -p -- path/to/file.py`
32	- Do not change anything yet
33
34	### Step 2: Cover First
35
36	If the code lacks tests, add tests before simplifying. You need a safety net:
37
38	```python
39	def test_generate_skill_name_sanitizes_input():
40	assert generate_skill_name("my repo") == "my-repo"
41	assert generate_skill_name("My Repo!") == "my-repo"
42	assert generate_skill_name(" spaces ") == "spaces"
43	```
44
45	Run them, confirm they pass. Now you can simplify safely.
46
47	### Step 3: Apply Simplifications Incrementally
48
49	Apply one simplification at a time, running tests after each:
50
51	#### Deep Nesting → Guard Clauses
52
53	```python
54	# BAD: Pyramid of doom
55	def process_skill(skill):
56	if skill is not None:
57	if skill.get("name"):
58	if len(skill["name"]) > 0:
59	return skill["name"].lower()
60	return None
61	return None
62
63	# GOOD: Guard clauses
64	def process_skill(skill):
65	if not skill:
66	return None
67	if not skill.get("name"):
68	return None
69	return skill["name"].lower()
70	```
71
72	#### Long Functions → Extracted Helpers
73
74	```python
75	# BAD: One function doing three jobs
76	def export_skill(repo: str) -> bytes:
77	# Fetch files
78	files = []
79	for branch in ["main", "master"]:
80	try:
81	contents = github_client.get_contents(repo, branch)
82	files = contents
83	break
84	except Exception:
85	continue
86
87	# Filter relevant files
88	relevant = [f for f in files if f.path.endswith((".md", ".py", ".ts"))]
89
90	# Build zip
91	buf = io.BytesIO()
92	with zipfile.ZipFile(buf, "w") as zf:
93	for f in relevant:
94	zf.writestr(f.path, f.decoded_content)
95	return buf.getvalue()
96
97	# GOOD: Each function does one thing
98	def export_skill(repo: str) -> bytes:
99	files = fetch_repo_files(repo)
100	relevant = filter_skill_files(files)
101	return build_zip(relevant)
102
103	def fetch_repo_files(repo: str) -> list:
104	for branch in ["main", "master"]:
105	try:
106	return github_client.get_contents(repo, branch)
107	except Exception:
108	continue
109	return []
110
111	def filter_skill_files(files: list) -> list:
112	return [f for f in files if f.path.endswith((".md", ".py", ".ts"))]
113
114	def build_zip(files: list) -> bytes:
115	buf = io.BytesIO()
116	with zipfile.ZipFile(buf, "w") as zf:
117	for f in files:
118	zf.writestr(f.path, f.decoded_content)
119	return buf.getvalue()
120	```
121
122	#### Generic Names → Descriptive Names
123
124	```python
125	# BAD
126	def process(d, r):
127	result = []
128	for item in d:
129	if item["type"] == r:
130	result.append(item)
131	return result
132
133	# GOOD
134	def filter_files_by_type(files: list[dict], file_type: str) -> list[dict]:
135	return [f for f in files if f["type"] == file_type]
136	```
137
138	#### Duplicated Logic → Shared Functions
139
140	```python
141	# BAD: Same validation in three places
142	def create_skill(name: str):
143	if not name or len(name) > 100:
144	raise ValueError("Invalid name")
145	...
146
147	def update_skill(name: str):
148	if not name or len(name) > 100:
149	raise ValueError("Invalid name")
150	...
151
152	# GOOD
153	def validate_skill_name(name: str) -> None:
154	if not name or len(name) > 100:
155	raise ValueError("Skill name must be 1-100 characters")
156
157	def create_skill(name: str):
158	validate_skill_name(name)
159	...
160	```
161
162	### Step 4: Verify Nothing Changed
163
164	Run the full test suite after each simplification:
165
166	```bash
167	pytest tests/ -v
168	```
169
170	If any test fails, revert that specifi

People who liked this also viewed

6 picks

Type