You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Description: AI states tasks are complete before verifying builds/tests (e.g., Dockerfile changes, conversion to uv).
43
-
Suggested Instruction: "Before declaring a task complete: run required verification (build/lint/test) and explicitly report PASS/FAIL for each. Never claim completion without evidence."
44
-
Placement: `.github/copilot-instructions.md` (workflow enforcement) and `taming-copilot.instructions.md` (concise verification rule).
45
-
46
-
## 2. Excessive Verbosity / Micro-Step Narration
47
-
Description: Over-detailed narration for trivial actions increases noise.
48
-
Suggested Instruction: "Batch related minor edits; summarize results in one concise paragraph—avoid step-by-step narration for mechanical fixes."
49
-
Placement: `taming-copilot.instructions.md`.
50
-
51
-
## 3. Large Rewrites Instead of Minimal Diffs
52
-
Description: Performed broad Dockerfile rewrites or code changes when user requested minimal invasive fixes.
53
-
Suggested Instruction: "When the user requests a fix, first attempt a surgical diff (limit scope to lines directly causing failure). Provide rationale if a broader refactor is unavoidable."
54
-
Placement: `taming-copilot.instructions.md` (Surgical Code Modification) and reinforce in `.github/copilot-instructions.md`.
55
-
56
-
## 4. Ignoring Explicit Directives (e.g., Do Not Recreate Deleted Files)
57
-
Description: Created shim after instruction that deleted files should not be recreated.
58
-
Suggested Instruction: "If user forbids an action (e.g., recreating a file), treat that as a hard constraint—adapt code/tests instead; flag any ambiguity before proceeding."
59
-
Placement: `taming-copilot.instructions.md` (Primacy of User Directives clarification).
60
-
61
-
## 5. Trial-and-Error Loops Without Holistic Analysis
62
-
Description: Repeated incremental Dockerfile changes (PATH/permissions) instead of planning full correct sequence.
63
-
Suggested Instruction: "After two consecutive failure iterations in same context, pause and produce a consolidated root-cause analysis and end-state patch plan before further edits."
64
-
Placement: `.github/copilot-instructions.md` (Debugging section) and `dockerfile.instructions.md` (methodical change guidance).
65
-
66
-
## 6. Overuse of Intermediate Confirmation Questions
67
-
Description: Asked for confirmation on obvious next actions.
68
-
Suggested Instruction: "Do not request confirmation for clearly implied next steps; proceed unless material ambiguity affects outcome."
69
-
Placement: `taming-copilot.instructions.md`.
70
-
71
-
## 7. Overwriting Functionality Without Preserving Behavior
72
-
Description: Property removed (Widget.name) to satisfy linter without validating design intent.
73
-
Suggested Instruction: "When resolving lint/type issues, prefer targeted fixes (type hints, guards) over removing/altering public API—flag potential behavior changes before applying."
41
+
## 1. Task Completion and Verification Standards
42
+
Description: AI states tasks complete without verification, uses excessive verbosity, or makes large rewrites instead of minimal fixes.
43
+
Suggested Instruction: "Always verify before claiming completion: run build/lint/test and report results. Keep explanations brief. Make smallest possible changes first."
44
+
Placement: `.github/copilot-instructions.md` (workflow enforcement) and `taming-copilot.instructions.md`.
45
+
46
+
## 2. User Directive Compliance
47
+
Description: Ignoring explicit user constraints (e.g., don't recreate deleted files) or overriding requests with best practices.
48
+
Suggested Instruction: "User requests always win over best practices. If user says delete/remove something, do it immediately without suggesting alternatives."
49
+
Placement: `taming-copilot.instructions.md` (strengthen Primacy of User Directives).
50
+
51
+
## 3. Iterative Problem-Solving and Failure Recovery
52
+
Description: Trial-and-error loops without analysis, redundant rebuilds, or sequential failed patches without fallback plans.
53
+
Suggested Instruction: "After 2 failures: stop and analyze the root cause completely. Draft the full solution, then apply once."
54
+
Placement: `.github/copilot-instructions.md` (Debugging section) and `dockerfile.instructions.md`.
55
+
56
+
## 4. Environment and Tool Context Awareness
57
+
Description: Missing environment verification, wrong tool usage (system vs project), or not using established patterns.
58
+
Suggested Instruction: "Always use uv commands for Python projects: `uv run -m pytest`, `uv add <library>`, `uv run`. Never use pytest or python directly. Verify files exist before suggesting fixes."
59
+
Placement: `python.instructions.md`, `devcontainer.instructions.md`, and `.github/copilot-instructions.md`.
60
+
61
+
## 5. Code Quality and API Preservation
62
+
Description: Removing functionality to satisfy linter, altering public APIs, or making behavioral changes without flagging risks.
63
+
Suggested Instruction: "Never remove public methods/properties to fix lints. Add type hints instead. Always mention if behavior might change."
74
64
Placement: `python.instructions.md` (Error Handling / Style) and `taming-copilot.instructions.md`.
75
65
76
-
## 8. Unnecessary Workarounds Before Canonical Fix (behave skip)
77
-
Description: Added skip guard instead of installing missing dependency.
78
-
Suggested Instruction: "Prefer resolving root cause (install required dependency) before adding conditional skips; only introduce guard if dependency is intentionally optional."
66
+
## 6. Testing Strategy and Maintenance
67
+
Description: Complex test patching, testing private methods, unnecessary workarounds, or deleting tests without consideration.
68
+
Suggested Instruction: "Test public APIs only. Install missing dependencies instead of adding skips. If user wants tests deleted, delete them immediately."
79
69
Placement: `testing.instructions.md`.
80
70
81
-
## 9. Import Path Confusion and Path Hacks
82
-
Description: Multiple sys.path manipulations before structural import review.
83
-
Suggested Instruction: "For import errors: first inspect package layout and existing __init__.py files; avoid sys.path hacks unless temporary and documented."
Suggested Instruction: "Be brief. Don't ask permission for obvious next steps. Only implement what was requested. Run tests after changes and report pass/fail."
79
+
Placement: `.github/copilot-instructions.md` and `taming-copilot.instructions.md`.
80
+
81
+
## 9. Docker and Container Signal Handling
82
+
Description: Container processes don't respond to Ctrl-C/SIGINT properly, entrypoint scripts use sudo/permissions incorrectly.
83
+
Key Pattern: Multiple conversations about fixing signal forwarding in Docker containers.
84
+
Suggested Instruction: "Use `gosu` with `exec` in production entrypoint scripts to drop privileges and forward signals. Sudo is acceptable for devcontainer usage. Ensure CMD uses direct command execution (not shell wrapping) for proper signal delivery. When docker.sock is mounted, fix permissions in entrypoint with: `chown ${USER}:${USER} /var/run/docker.sock >/dev/null 2>&1 || true`."
85
+
Placement: `dockerfile.instructions.md` (add signal handling section).
86
+
87
+
## 10. Web Framework Integration Debugging
88
+
Description: Frontend clicks/navigation not working due to JavaScript framework conflicts (HTMX boost interfering with redirects).
89
+
Key Pattern: Debugging template and route interactions where client-side frameworks override expected behavior.
90
+
Suggested Instruction: "Check for JS framework conflicts when links/forms don't work. Add `data-*-boost='false'` or equivalent to opt out of framework interception."
Description: Using system tools instead of project-managed tools (uv run -m pytest).
95
+
Key Pattern: Consistent pattern of users correcting to use project tooling.
96
+
Suggested Instruction: "Always use uv for Python projects. Use `uv run -m pytest` not `pytest`. Use `uv add <library>` not direct installs. Use `uv run` not direct python."
Description: When files are deleted, imports and tests still reference them causing ImportErrors during collection.
101
+
Key Pattern: User deletes files, agent tries to recreate them instead of cleaning up references.
102
+
Suggested Instruction: "When user deletes files: update all imports to use alternatives, move skip() before imports in tests, delete tests that can't be salvaged. Never recreate deleted files."
84
103
Placement: `python.instructions.md` and `testing.instructions.md`.
85
104
86
-
## 10. Dynamic Import Patching Fragility in Tests
87
-
Description: Complex patching of internals for Widget.from_dict.
88
-
Suggested Instruction: "Favor exercising public API with supplied test doubles over patching function __globals__; refactor for dependency injection when patching becomes brittle."
89
-
Placement: `testing.instructions.md`.
105
+
## 13. Make Command Flag Usage
106
+
Description: Adding unnecessary flags like `-s` or `-j1` to make commands causes build system failures.
107
+
Key Pattern: Agent adds flags to make commands without explicit need or user request.
108
+
Suggested Instruction: "Use make commands without flags unless required for the specific task. Do not add `-s`, `-j1`, or other flags unless the user requests them."
109
+
Placement: `makefile.instructions.md` and `.github/copilot-instructions.md`.
90
110
91
-
## 11. Redundant Rebuilds Without Caching Strategy
92
-
Description: Many Docker builds adjusting uv install path sequentially.
93
-
Suggested Instruction: "When iterating on Dockerfile dependency install failures: draft full corrected RUN block locally, then apply once; explain cache implications."
94
-
Placement: `dockerfile.instructions.md`.
111
+
## 14. Package Installation with uv
112
+
Description: Using incorrect uv add syntax or missing development/notebook dependency flags.
113
+
Key Pattern: Installing packages without proper context flags for development or notebook environments.
114
+
Suggested Instruction: "Use `uv add <library_name>` for production dependencies. Use `uv add --dev <library_name>` for development dependencies. Use `uv add --group notebook <library_name>` for notebook-specific dependencies. Never use direct package installation tools."
115
+
Placement: `python.instructions.md` and `.github/copilot-instructions.md`.
95
116
96
-
## 12. Missing Post-Change Validation Summary
97
-
Description: Changes applied without immediate lint/test run summary.
98
-
Suggested Instruction: "After any multi-file patch: run lint + focused tests; output concise PASS/FAIL matrix (Lint | Unit | Integration | Build)."
Description: Added extra abstractions beyond step scope.
103
-
Suggested Instruction: "Limit implementation to explicit scope; list potential enhancements separately under 'Optional Next Steps' instead of implementing."
104
-
Placement: `taming-copilot.instructions.md`.
119
+
**IMPORTANT:** When merging these instruction improvements, update `.github/copilot-instructions.md` and other .github instruction files to use **uv commands by default** for Python projects.
120
+
121
+
Required updates:
122
+
1.**Workflow section** - Change all examples to use uv commands
123
+
2.**Python environment configuration** - Use `uv run` commands instead of direct python
124
+
3.**Tool usage examples** - Replace `pytest` with `uv run -m pytest`, replace installs with `uv add <library>`
125
+
4.**Docker entrypoint example** - Add the complete entrypoint script from this project's Dockerfile to `dockerfile.instructions.md`
126
+
5.**VERSION file** - Run `echo "$(date)" > .github/VERSION` to mark when these instruction improvements were implemented for future .specstory/history analysis
127
+
128
+
This ensures all instruction files consistently use uv for Python development workflows.
105
129
106
-
## 14. Excessive Patch Churn on Single File
107
-
Description: Multiple rewrites of test file before stable version.
108
-
Suggested Instruction: "Before large test refactor: outline intended final structure (sections/assert focus) in scratch, then apply single patch."
109
-
Placement: `testing.instructions.md`.
110
130
111
-
## 15. Lack of Early Environment/Context Verification
112
-
Description: Suggested fixes (Node missing) without verifying actual installed paths.
113
-
Suggested Instruction: "Verify existence/path of referenced binaries or configs before prescribing installation or cleanup actions."
114
-
Placement: `devcontainer.instructions.md` and `.github/copilot-instructions.md`.
115
-
116
-
## 16. Verbose Repetition of Unchanged Checklists
117
-
Description: Reprinted full checklist after each minor update.
118
-
Suggested Instruction: "When reporting progress, only show delta (updated steps) unless user explicitly requests full checklist."
119
-
Placement: `.github/copilot-instructions.md`.
120
-
121
-
## 17. Insufficient Guard Against Removing Needed Features
Suggested Instruction: "Before deleting or replacing a build stage/file: enumerate dependents (FROM targets, scripts) and confirm none required; otherwise adapt rather than remove."
124
-
Placement: `dockerfile.instructions.md`.
125
-
126
-
## 18. Not Flagging Potential Behavioral Regressions in Lint Fixes
127
-
Description: Silent behavioral change to satisfy linter.
128
-
Suggested Instruction: "If a lint fix alters behavior or API surface, annotate commit note and request confirmation if risk > low."
129
-
Placement: `python.instructions.md`.
130
-
131
-
## 19. Mixing Planning Philosophy (Verbose vs Concise)
132
-
Description: Conflict between expansive planning and mandate for concise output.
133
-
Suggested Instruction: "Use concise mode by default; detailed expansion only when ambiguity > medium or on explicit user request."
134
-
Placement: `taming-copilot.instructions.md` & `.github/copilot-instructions.md` (clarify priority of concision when tension arises).
135
-
136
-
## 20. Failure Recovery Strategy Not Explicit
137
-
Description: Sequential failed patches without fallback plan articulation.
138
-
Suggested Instruction: "After two failed patch applications: present fallback options (smaller diff, manual segment edit) before retrying."
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+12-1Lines changed: 12 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,6 +19,17 @@ Plan extensively before each function call, and reflect on outcomes to ensure co
19
19
20
20
Your goal is to deliver a perfect, production-ready solution for this project, following all project conventions and best practices.
21
21
22
+
## Python Project Standards
23
+
- Always use uv commands for Python projects: `uv run -m pytest`, `uv add <library>`, `uv run`
24
+
- Never use pytest or python directly
25
+
- Use `uv add <library_name>` for production dependencies
26
+
- Use `uv add --dev <library_name>` for development dependencies
27
+
- Use `uv add --group notebook <library_name>` for notebook-specific dependencies
28
+
- Always verify before claiming completion: run build/lint/test and report results
29
+
- After 2 failures: stop and analyze the root cause completely, then apply full solution once
30
+
- User requests always win over best practices
31
+
- Make smallest possible changes first
32
+
22
33
# Documentation and References
23
34
24
35
You may create a .devplanning directory.
@@ -47,7 +58,7 @@ Keep the .devplanning directory organized and up to date, it should contain:
47
58
5. Develop a clear, step-by-step plan. Break down the fix into manageable, incremental steps. Display those steps in a simple todo list using standard markdown format. Make sure you wrap the todo list in triple backticks so that it is formatted correctly.
48
59
6. Implement the fix incrementally. Make small, testable code changes.
49
60
7. Debug as needed. Use debugging techniques to isolate and resolve issues.
50
-
8. Test frequently. Run tests after each change to verify correctness.
61
+
8. Test frequently. Run tests after each change to verify correctness using `uv run -m pytest`.
51
62
9. Iterate until the root cause is fixed and all tests pass.
52
63
10. Reflect and validate comprehensively. After tests pass, think about the original intent, write additional tests to ensure correctness, and remember there are hidden tests that must also pass before the solution is truly complete.
0 commit comments