engineering-loop

Name: engineering-loop
Author: neuromechanist

37stars7forks

How to install engineering-loop?

neuromechanist/research-skills/engineering-loop

$npx -y skills add neuromechanist/research-skills --skill engineering-loop

Installs into the current project.

Summary

Use this skill when the user asks to \"implement this change\", \"fix this issue\", \"add this feature\", \"make this change properly\", \"ship this\", or for any ordinary single-PR development task: one issue, one branch, one pull request. For multi-phase features use epic-dev;

Files · 1

View on GitHub

SKILL.md

1	# Engineering Loop (single change, one PR)
2
3	The standard loop for one ordinary change: spec to merged PR with review and
4	verification. Lightweight counterpart to the epic-dev workflow.
5
6	## Scale check (before starting)
7
8	\| Signal \| Route \|
9	\| --- \| --- \|
10	\| One reviewable unit: one subsystem, roughly a day or less \| This skill. \|
11	\| 2+ independently reviewable/testable units, or multiple subsystems \| epic-dev (phased epic with worktrees). \|
12	\| You have not worked in this code before \| codebase-onboarding first, then return here. \|
13	\| Behavior is wrong and cause unknown \| debugging skill first; the fix then follows this loop. \|
14	\| No issue exists yet \| Create one (except trivial fixes); it is the durable spec. \|
15
16	## The loop
17
18	1. Read the spec. `gh issue view N`. If the request is a one-line or
19	ambiguous instruction, restate your interpretation in one sentence with an
20	opt-out ("proceeding on that basis; tell me if you meant X") and continue;
21	do not stall.
22	2. Explore just enough, then find the pattern to mirror. Read the target
23	area and locate an existing correct implementation of the same shape
24	(a similar route, a similar test, the sibling module). New code mirrors
25	the house pattern; do not invent a new one for an ordinary change. If the
26	change builds on a third-party API you have not used in this repo, probe
27	the installed version first (import and inspect; do not trust memory).
28	3. Branch. `gh issue develop N --checkout` (or
29	`git checkout -b feature/issue-N-<slug>` per repo convention). Never work
30	on the default branch.
31	4. Pin test first (refactors only). If the change claims to preserve
32	behavior, commit #1 is a characterization test captured against the
33	ORIGINAL code (route inventory, golden output). A pin test written after
34	the move proves nothing.
35	5. Implement the smallest coherent diff. Match surrounding style. Discard
36	incidental churn before committing (lockfiles, formatting of untouched
37	lines). No backward-compatibility shims when the user confirms zero
38	consumers; remove outright and preserve the substantive invariant instead.
39	For every new guard or error path, decide fail-open vs fail-closed
40	explicitly and say why in the code or PR. If you find a genuine adjacent
41	bug outside the assigned scope: fix it only if it is small and
42	mechanistically connected to the change you are already making, and
43	disclose it under its own heading in the PR with evidence; otherwise file
44	an issue. Never fold it silently into the main diff.
45	6. Gate every commit. Format, lint, typecheck, test; the bar is zero NEW
46	diagnostics against the MEASURED baseline (measure it; do not trust a
47	documented number, and note discrepancies). Python: `uv run ruff format
48	&& uv run ruff check --fix && uv run ty check && uv run pytest`.
49	JS/TS: `bun run biome check --write && bun test` (or the project's
50	configured commands). Commit atomically: subject under 50 characters, no
51	emojis, no AI attribution. For changes to decision logic (parsing,
52	approve/deny paths, routing, security gates), green tests alone are not
53	enough: run a repeatable scenario suite and quote the before/after scores
54	in the PR.
55	7. Long-running steps (benchmarks, big builds, batch jobs over ~10
56	minutes): detach them per `references/background-jobs.md`; never leave
57	them as session-tracked shells. Commit expensive-to-reproduce results the
58	moment they land, separately from code.
59	8. Push and open the PR. Body: what changed, why (link "Closes #N"), and
60	what was tested with commands and counts. No emojis, no AI attribution.
61	Semantic line breaks remain the default for prose source, but GitHub issue
62	and PR bodies are the exception: keep each paragraph on one source line and
63	separate paragraphs with blank lines; do not insert sentence- or
64	clause-level newlines inside a paragraph.
65	Verify any user-supplied factual claim (dates, numbers, attributions)
66	against available evidence before writing it into a PR, issue, or other
67	durable document; if the evidence contradicts the claim, surface the
68	discrepancy instead of transcribing it.
69	9. Review. Run the pr-review-toolkit skill (or repo review command) on
70	the PR. Address ALL findings: fix, or reject with a one-sentence reason
71	posted to the PR ("false positive" / "intentionally different by design").
72	No silent drops; a deleted test that held the only coverage of a scenario
73	is a blocking gap, not a nit.
74	10. CI, then merge. Wait for checks (background watch:
75	`gh pr

People who liked this also viewed

6 picks

Type

engineering-loop

37stars7forks

View on GitHub

How to install engineering-loop?

neuromechanist/research-skills/engineering-loop

$npx -y skills add neuromechanist/research-skills --skill engineering-loop

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Engineering Loop (single change, one PR)
2
3	The standard loop for one ordinary change: spec to merged PR with review and
4	verification. Lightweight counterpart to the epic-dev workflow.
5
6	## Scale check (before starting)
7
8	\| Signal \| Route \|
9	\| --- \| --- \|
10	\| One reviewable unit: one subsystem, roughly a day or less \| This skill. \|
11	\| 2+ independently reviewable/testable units, or multiple subsystems \| epic-dev (phased epic with worktrees). \|
12	\| You have not worked in this code before \| codebase-onboarding first, then return here. \|
13	\| Behavior is wrong and cause unknown \| debugging skill first; the fix then follows this loop. \|
14	\| No issue exists yet \| Create one (except trivial fixes); it is the durable spec. \|
15
16	## The loop
17
18	1. Read the spec. `gh issue view N`. If the request is a one-line or
19	ambiguous instruction, restate your interpretation in one sentence with an
20	opt-out ("proceeding on that basis; tell me if you meant X") and continue;
21	do not stall.
22	2. Explore just enough, then find the pattern to mirror. Read the target
23	area and locate an existing correct implementation of the same shape
24	(a similar route, a similar test, the sibling module). New code mirrors
25	the house pattern; do not invent a new one for an ordinary change. If the
26	change builds on a third-party API you have not used in this repo, probe
27	the installed version first (import and inspect; do not trust memory).
28	3. Branch. `gh issue develop N --checkout` (or
29	`git checkout -b feature/issue-N-<slug>` per repo convention). Never work
30	on the default branch.
31	4. Pin test first (refactors only). If the change claims to preserve
32	behavior, commit #1 is a characterization test captured against the
33	ORIGINAL code (route inventory, golden output). A pin test written after
34	the move proves nothing.
35	5. Implement the smallest coherent diff. Match surrounding style. Discard
36	incidental churn before committing (lockfiles, formatting of untouched
37	lines). No backward-compatibility shims when the user confirms zero
38	consumers; remove outright and preserve the substantive invariant instead.
39	For every new guard or error path, decide fail-open vs fail-closed
40	explicitly and say why in the code or PR. If you find a genuine adjacent
41	bug outside the assigned scope: fix it only if it is small and
42	mechanistically connected to the change you are already making, and
43	disclose it under its own heading in the PR with evidence; otherwise file
44	an issue. Never fold it silently into the main diff.
45	6. Gate every commit. Format, lint, typecheck, test; the bar is zero NEW
46	diagnostics against the MEASURED baseline (measure it; do not trust a
47	documented number, and note discrepancies). Python: `uv run ruff format
48	&& uv run ruff check --fix && uv run ty check && uv run pytest`.
49	JS/TS: `bun run biome check --write && bun test` (or the project's
50	configured commands). Commit atomically: subject under 50 characters, no
51	emojis, no AI attribution. For changes to decision logic (parsing,
52	approve/deny paths, routing, security gates), green tests alone are not
53	enough: run a repeatable scenario suite and quote the before/after scores
54	in the PR.
55	7. Long-running steps (benchmarks, big builds, batch jobs over ~10
56	minutes): detach them per `references/background-jobs.md`; never leave
57	them as session-tracked shells. Commit expensive-to-reproduce results the
58	moment they land, separately from code.
59	8. Push and open the PR. Body: what changed, why (link "Closes #N"), and
60	what was tested with commands and counts. No emojis, no AI attribution.
61	Semantic line breaks remain the default for prose source, but GitHub issue
62	and PR bodies are the exception: keep each paragraph on one source line and
63	separate paragraphs with blank lines; do not insert sentence- or
64	clause-level newlines inside a paragraph.
65	Verify any user-supplied factual claim (dates, numbers, attributions)
66	against available evidence before writing it into a PR, issue, or other
67	durable document; if the evidence contradicts the claim, surface the
68	discrepancy instead of transcribing it.
69	9. Review. Run the pr-review-toolkit skill (or repo review command) on
70	the PR. Address ALL findings: fix, or reject with a one-sentence reason
71	posted to the PR ("false positive" / "intentionally different by design").
72	No silent drops; a deleted test that held the only coverage of a scenario
73	is a blocking gap, not a nit.
74	10. CI, then merge. Wait for checks (background watch:
75	`gh pr

People who liked this also viewed

6 picks

Type