Skip to content

Commit 01442ce

Browse files
MarkusNeusingerMarkusNeusinger
committed
feat: add planning documents for bug fixes, feature implementation, and application validation
- Introduced `bug.md` for structured bug fix planning - Added `feature.md` for feature implementation planning - Created `test.md` for comprehensive application validation testing - Developed `review.md` for reviewing work against specifications - Established `context.md` for conditional documentation guidance
1 parent 68271c0 commit 01442ce

7 files changed

Lines changed: 655 additions & 0 deletions

File tree

‎agentic/commands/bug.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Bug Fix Planning
2+
3+
Create a plan to fix the bug using the specified markdown `Plan Format`. Research the codebase, identify the root cause,
4+
and create a thorough fix plan.
5+
6+
## Variables
7+
8+
run_id: $1
9+
prompt: $2
10+
11+
## Instructions
12+
13+
- If the run_id or prompt is not provided, stop and ask the user to provide them.
14+
- Investigate the bug described in the `prompt`
15+
- Identify the root cause before planning the fix
16+
- Create the plan in the `agentic/specs/` directory with filename: `bug-{run_id}-{descriptive-name}.md`
17+
- Replace `{descriptive-name}` with a short name based on the bug (e.g., "fix-api-timeout", "null-pointer-plots")
18+
- Research the codebase starting with `README.md`
19+
- Replace every <placeholder> in the `Plan Format` with the requested value
20+
21+
## Codebase Structure
22+
23+
- `README.md` - Project overview and instructions (start here)
24+
- `api/` - FastAPI backend
25+
- `main.py` - App entry point
26+
- `routers/` - API route handlers
27+
- `services/` - Business logic
28+
- `app/` - React frontend (Vite + TypeScript)
29+
- `src/` - Source code
30+
- `core/` - Shared Python modules
31+
- `models/` - Pydantic models
32+
- `database/` - Database utilities
33+
- `plots/` - Plot specifications and implementations
34+
- `tests/` - Test suites
35+
- `agentic/` - Agentic Layer
36+
- `commands/` - Prompt templates
37+
- `workflows/` - Workflow scripts (`uv run`)
38+
- `specs/` - Generated plans
39+
40+
## Plan Format
41+
42+
```md
43+
# Bug: <bug name>
44+
45+
## Metadata
46+
47+
run_id: `{run_id}`
48+
prompt: `{prompt}`
49+
50+
## Bug Description
51+
52+
<describe the bug, symptoms, and when it occurs>
53+
54+
## Root Cause Analysis
55+
56+
<explain the root cause of the bug after investigating the code>
57+
58+
## Affected Files
59+
60+
Files that need to be modified to fix the bug:
61+
62+
<list files with bullet points explaining why each needs changes>
63+
64+
## Fix Strategy
65+
66+
IMPORTANT: Execute every step in order, top to bottom.
67+
68+
### 1. <First Fix Step>
69+
70+
- <specific action>
71+
- <specific action>
72+
73+
### 2. <Second Fix Step>
74+
75+
- <specific action>
76+
- <specific action>
77+
78+
### 3. Add/Update Tests
79+
80+
- <add test to prevent regression>
81+
- <verify fix with existing tests>
82+
83+
## Validation Commands
84+
85+
Execute these commands to validate the fix:
86+
87+
- `uv run pytest tests/ -v` - Run test suite
88+
- `uv run python -m py_compile api/**/*.py` - Check Python syntax
89+
- <additional validation commands>
90+
91+
## Notes
92+
93+
<optional: edge cases, related issues, or follow-up work>
94+
```
95+
96+
## Bug
97+
98+
Use the bug description from the `prompt` variable.
99+
100+
## Report
101+
102+
Return the path to the plan file created.

‎agentic/commands/context.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Conditional Documentation Guide
2+
3+
This prompt helps you determine what documentation you should read based on the specific changes you need to make in the codebase. Review the conditions below and read the relevant documentation before proceeding with your task.
4+
5+
## Instructions
6+
7+
- Review the task you've been asked to perform
8+
- Check each documentation path in the Conditional Documentation section
9+
- For each path, evaluate if any of the listed conditions apply to your task
10+
- IMPORTANT: Only read the documentation if any one of the conditions match your task
11+
- IMPORTANT: You don't want to excessively read documentation. Only read the documentation if it's relevant to your task.
12+
13+
## Conditional Documentation
14+
15+
- README.md
16+
- Conditions:
17+
- When first understanding the project structure
18+
- When you want to learn the commands to start or stop the server
19+
- When setting up the development environment
20+
21+
- docs/ai_docs/project-guide.md
22+
- Conditions:
23+
- When understanding the full project architecture
24+
- When working on workflows or automation
25+
- When contributing to the project
26+
27+
- api/
28+
- Conditions:
29+
- When working with FastAPI backend
30+
- When modifying API routes or services
31+
- When working with database operations
32+
33+
- app/
34+
- Conditions:
35+
- When working with the React frontend
36+
- When modifying UI components
37+
- When working with TypeScript code
38+
39+
- core/
40+
- Conditions:
41+
- When working with shared Python modules
42+
- When modifying Pydantic models
43+
- When working with database utilities
44+
45+
- plots/
46+
- Conditions:
47+
- When working with plot specifications
48+
- When implementing new visualizations
49+
- When modifying existing plot implementations
50+
51+
- agentic/
52+
- Conditions:
53+
- When working with agentic commands or workflows
54+
- When creating or modifying prompt templates
55+
- When working with specs or context documentation

‎agentic/commands/dokument.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Document Feature
2+
3+
Generate concise markdown documentation for implemented features by analyzing code changes and specifications. This command creates documentation in the `agentic/context/` directory based on git diff analysis against the main branch and the original feature specification.
4+
5+
## Variables
6+
7+
run_id: $1
8+
spec_path: $2 if provided, otherwise leave it blank
9+
documentation_screenshots_dir: $3 if provided, otherwise leave it blank
10+
11+
## Instructions
12+
13+
### 1. Analyze Changes
14+
- Run `git diff origin/main --stat` to see files changed and lines modified
15+
- Run `git diff origin/main --name-only` to get the list of changed files
16+
- For significant changes (>50 lines), run `git diff origin/main <file>` on specific files to understand the implementation details
17+
18+
### 2. Read Specification (if provided)
19+
- If `spec_path` is provided, read the specification file to understand:
20+
- Original requirements and goals
21+
- Expected functionality
22+
- Success criteria
23+
- Use this to frame the documentation around what was requested vs what was built
24+
25+
### 3. Analyze and Copy Screenshots (if provided)
26+
- If `documentation_screenshots_dir` is provided, list and examine screenshots
27+
- Create `agentic/context/assets/` directory if it doesn't exist
28+
- Copy all screenshot files (*.png) from `documentation_screenshots_dir` to `agentic/context/assets/`
29+
- Preserve original filenames
30+
- Use `cp` command to copy files
31+
- Use visual context to better describe UI changes or visual features
32+
- Reference screenshots in documentation using relative paths (e.g., `assets/screenshot-name.png`)
33+
34+
### 4. Generate Documentation
35+
- Create a new documentation file in `agentic/context/` directory
36+
- Filename format: Match the spec filename (e.g., if spec is `feature-abc123-add-auth.md`, create `feature-abc123-add-auth.md`)
37+
- If no spec_path provided, use: `feature-{run_id}-{descriptive-name}.md`
38+
- Follow the Documentation Format below
39+
- Focus on:
40+
- What was built (based on git diff)
41+
- How it works (technical implementation)
42+
- How to use it (user perspective)
43+
- Any configuration or setup required
44+
45+
### 5. Update Context Documentation
46+
- After creating the documentation file, read `agentic/commands/context.md`
47+
- Add an entry for the new documentation file with appropriate conditions
48+
- The entry should help future developers know when to read this documentation
49+
- Format the entry following the existing pattern in the file
50+
51+
### 6. Final Output
52+
- When you finish writing the documentation and updating context.md, return exclusively the path to the documentation file created and nothing else
53+
54+
## Codebase Structure
55+
56+
- `README.md` - Project overview (start here)
57+
- `api/` - FastAPI backend
58+
- `main.py` - App entry point
59+
- `routers/` - API route handlers
60+
- `services/` - Business logic
61+
- `app/` - React frontend (Vite + TypeScript)
62+
- `src/` - Source code
63+
- `core/` - Shared Python modules
64+
- `models/` - Pydantic models
65+
- `database/` - Database utilities
66+
- `plots/` - Plot specifications and implementations
67+
- `tests/` - Test suites
68+
- `agentic/` - Agentic Layer
69+
- `commands/` - Prompt templates
70+
- `workflows/` - Workflow scripts (`uv run`)
71+
- `specs/` - Plans (what to do)
72+
- `context/` - Feature docs (what was done)
73+
- `docs/` - Static project documentation
74+
75+
## Documentation Format
76+
77+
```md
78+
# <Feature Title>
79+
80+
**Run ID:** <run_id>
81+
**Date:** <current date>
82+
**Specification:** <spec_path or "N/A">
83+
84+
## Overview
85+
86+
<2-3 sentence summary of what was built and why>
87+
88+
## Screenshots
89+
90+
<If documentation_screenshots_dir was provided and screenshots were copied>
91+
92+
![<Description>](assets/<screenshot-filename.png>)
93+
94+
## What Was Built
95+
96+
<List the main components/features implemented based on the git diff analysis>
97+
98+
- <Component/feature 1>
99+
- <Component/feature 2>
100+
- <etc>
101+
102+
## Technical Implementation
103+
104+
### Files Modified
105+
106+
<List key files changed with brief description of changes>
107+
108+
- `<file_path>`: <what was changed/added>
109+
- `<file_path>`: <what was changed/added>
110+
111+
### Key Changes
112+
113+
<Describe the most important technical changes in 3-5 bullet points>
114+
115+
## How to Use
116+
117+
<Step-by-step instructions for using the new feature>
118+
119+
1. <Step 1>
120+
2. <Step 2>
121+
3. <etc>
122+
123+
## Configuration
124+
125+
<Any configuration options, environment variables, or settings>
126+
127+
## Testing
128+
129+
<Brief description of how to test the feature>
130+
131+
## Notes
132+
133+
<Any additional context, limitations, or future considerations>
134+
```
135+
136+
## Context Entry Format
137+
138+
After creating the documentation, add this entry to `agentic/commands/context.md`:
139+
140+
```md
141+
- agentic/context/<your_documentation_file>.md
142+
- Conditions:
143+
- When working with <feature area>
144+
- When implementing <related functionality>
145+
- When troubleshooting <specific issues>
146+
```
147+
148+
## Report
149+
150+
- IMPORTANT: Return exclusively the path to the documentation file created and nothing else.

0 commit comments

Comments
 (0)