Skip to content

Commit 727051b

Browse files
iludeilude
committed
Create automated instruction improvement prompt system
- Created comprehensive prompt at .github/prompts/update-instructions.prompt.md - Prompt recreates the entire instruction improvement workflow we just completed - Includes all 14 improvement patterns from conversation analysis - Provides systematic approach to analyzing conversation history - Implements uv-first approach consistently throughout - Added intelligent VERSION timestamp handling for incremental analysis - Includes comprehensive verification and error handling - Added complete feature specification and documentation - Validated against our actual implementation (commit 07dcdbd) - Ready for future automated instruction improvements Key Features: - Incremental analysis: only process conversations newer than VERSION timestamp - Full analysis: scan all history when no VERSION file exists - File filtering logic with modification date comparison - Comprehensive error handling and recovery procedures Files created: - .devplanning/prompt-automation-feature/README.md - .devplanning/prompt-automation-feature/feature-spec.md - .devplanning/prompt-automation-feature/implementation-plan.md - .devplanning/prompt-automation-feature/workflow-documentation.md - .devplanning/prompt-automation-feature/validation.md - .github/prompts/update-instructions.prompt.md
1 parent 07dcdbd commit 727051b

File tree

6 files changed

+1020
-0
lines changed

6 files changed

+1020
-0
lines changed

‎.devplanning/prompt-automation-feature/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Prompt Automation Feature
2+
3+
## Overview
4+
Create a reusable prompt that can replicate the instruction improvement workflow we just completed. This prompt should analyze conversation history, identify patterns, consolidate improvements, and implement changes across the instruction ecosystem.
5+
6+
## Goal
7+
Generate `.github/prompts/update-instructions.prompt.md` that contains a comprehensive prompt for automated instruction improvements based on conversation history analysis.
8+
9+
## Context
10+
We just completed a manual process that:
11+
1. Analyzed conversation history files in `.specstory/history/*.md`
12+
2. Identified 14 common interaction issues
13+
3. Consolidated improvements into actionable patterns
14+
4. Updated 7 instruction files with uv-first approach
15+
5. Created VERSION timestamp for tracking
16+
6. Verified all changes with tests
17+
18+
## Deliverables
19+
- Feature specification document
20+
- Step-by-step implementation plan
21+
- Comprehensive prompt file at `.github/prompts/update-instructions.prompt.md`
22+
- Documentation for future usage
23+
24+
## Success Criteria
25+
The generated prompt should be able to:
26+
- Recreate the entire instruction improvement workflow
27+
- Analyze new conversation history since last VERSION timestamp
28+
- Apply consolidated improvement patterns systematically
29+
- Maintain consistency with our instruction file ecosystem
30+
- Include proper verification and testing steps

‎.devplanning/prompt-automation-feature/feature-spec.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Feature Specification: Automated Instruction Improvement Prompt
2+
3+
## Feature Description
4+
Create a comprehensive prompt that automates the instruction improvement workflow by analyzing conversation history and systematically updating instruction files based on identified patterns.
5+
6+
## Core Components
7+
8+
### 1. Historical Analysis Engine
9+
- **Input**: Conversation history files in `.specstory/history/*.md`
10+
- **Process**: Parse each file for interaction patterns and AI/user issues
11+
- **Output**: Structured analysis of common problems
12+
13+
### 2. Pattern Recognition System
14+
- **Input**: Analysis results from historical review
15+
- **Process**: Identify recurring themes and consolidate into actionable patterns
16+
- **Output**: Prioritized list of instruction improvements
17+
18+
### 3. Instruction File Orchestration
19+
- **Input**: Consolidated improvement patterns
20+
- **Process**: Map improvements to appropriate instruction files based on `applyTo` patterns
21+
- **Output**: Systematic updates across the instruction ecosystem
22+
23+
### 4. Verification Framework
24+
- **Input**: Updated instruction files
25+
- **Process**: Run tests, validate git operations, check for errors
26+
- **Output**: Confirmation of successful implementation
27+
28+
## Technical Requirements
29+
30+
### File Structure
31+
```
32+
.github/
33+
└── prompts/
34+
└── update-instructions.prompt.md
35+
```
36+
37+
### Dependencies
38+
- Existing instruction files in `.github/instructions/`
39+
- Main copilot instructions in `.github/copilot-instructions.md`
40+
- VERSION timestamp file for tracking analysis points
41+
- Test suite for verification
42+
43+
### Integration Points
44+
- Must work with current `.specstory/history/` file structure
45+
- Must respect existing `applyTo` patterns in instruction files
46+
- Must maintain uv-first approach for Python projects
47+
- Must create/update VERSION timestamp for future analysis
48+
49+
## Functional Requirements
50+
51+
### FR1: Historical Analysis
52+
The prompt must:
53+
- Parse all `.md` files in `.specstory/history/` since last VERSION timestamp
54+
- Extract interaction issues between user and AI
55+
- Identify problems AI encountered while solving requests
56+
- Create structured documentation of findings
57+
58+
### FR2: Pattern Consolidation
59+
The prompt must:
60+
- Group similar issues across multiple conversations
61+
- Prioritize patterns by frequency and impact
62+
- Generate actionable improvement suggestions
63+
- Map improvements to appropriate instruction files
64+
65+
### FR3: Systematic Implementation
66+
The prompt must:
67+
- Update instruction files with consolidated improvements
68+
- Maintain consistent language and formatting
69+
- Ensure uv-first approach for Python tooling
70+
- Add comprehensive examples where needed
71+
72+
### FR4: Verification and Tracking
73+
The prompt must:
74+
- Run full test suite to verify changes
75+
- Create git commit with detailed changelog
76+
- Update VERSION timestamp
77+
- Report success/failure status
78+
79+
## Non-Functional Requirements
80+
81+
### NFR1: Maintainability
82+
- Prompt should be self-documenting
83+
- Include clear step-by-step workflow
84+
- Provide troubleshooting guidance
85+
- Support incremental improvements
86+
87+
### NFR2: Reliability
88+
- Include error handling for missing files
89+
- Graceful degradation when history is limited
90+
- Validation of instruction file updates
91+
- Rollback guidance for failed implementations
92+
93+
### NFR3: Consistency
94+
- Maintain existing instruction file patterns
95+
- Preserve user-specific customizations
96+
- Follow established markdown formatting
97+
- Align with project coding standards
98+
99+
## User Stories
100+
101+
### US1: As a maintainer
102+
I want to run a single prompt that analyzes recent conversations and improves our instruction files, so that I can systematically enhance AI assistance quality without manual effort.
103+
104+
### US2: As a developer
105+
I want the instruction improvements to be tested and verified, so that I can trust the changes won't break existing workflows.
106+
107+
### US3: As a future user
108+
I want the improvement process to be repeatable and trackable, so that instruction quality continuously improves over time.
109+
110+
## Acceptance Criteria
111+
112+
### AC1: Complete Workflow Automation
113+
- [ ] Single prompt recreates entire manual process
114+
- [ ] No human intervention required for standard cases
115+
- [ ] Clear progress reporting throughout execution
116+
117+
### AC2: Quality Assurance
118+
- [ ] All instruction file updates are syntactically correct
119+
- [ ] Test suite passes after implementation
120+
- [ ] Git commit includes comprehensive changelog
121+
122+
### AC3: Future Compatibility
123+
- [ ] VERSION timestamp enables incremental analysis
124+
- [ ] Prompt can be run repeatedly without conflicts
125+
- [ ] New conversation patterns are automatically incorporated
126+
127+
## Implementation Risks
128+
129+
### Risk 1: File Format Changes
130+
**Impact**: Medium
131+
**Mitigation**: Include format validation and graceful handling of unexpected structures
132+
133+
### Risk 2: Instruction File Conflicts
134+
**Impact**: High
135+
**Mitigation**: Backup existing files before changes, provide rollback instructions
136+
137+
### Risk 3: Pattern Recognition Accuracy
138+
**Impact**: Medium
139+
**Mitigation**: Manual review checkpoints, conservative change approach
140+
141+
## Success Metrics
142+
- Successful recreation of our manual improvement process
143+
- 100% test pass rate after implementation
144+
- Clean git commit with no manual fixups required
145+
- Comprehensive instruction file coverage

‎.devplanning/prompt-automation-feature/implementation-plan.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Implementation Plan: Automated Instruction Improvement Prompt
2+
3+
## Phase 1: Analysis and Planning
4+
5+
### Step 1: Review Current Implementation
6+
- [x] Analyze recent commit changes (07dcdbd)
7+
- [x] Document the 14 improvement patterns we implemented
8+
- [x] Map changes to instruction files
9+
- [x] Understand VERSION timestamp usage
10+
11+
### Step 2: Extract Workflow Patterns
12+
- [x] Document the exact sequence of operations we performed
13+
- [x] Identify decision points and branching logic
14+
- [x] Capture file selection criteria
15+
- [x] Document verification steps
16+
17+
### Step 3: Create Prompt Structure
18+
- [x] Design main workflow sections
19+
- [x] Define input/output formats
20+
- [x] Plan error handling approaches
21+
- [x] Structure verification checkpoints
22+
23+
## Phase 2: Prompt Development
24+
25+
### Step 4: Core Workflow Implementation
26+
- [x] Historical analysis section
27+
- [x] Pattern recognition logic
28+
- [x] File mapping strategies
29+
- [x] Implementation sequencing
30+
31+
### Step 5: Instruction File Templates
32+
- [x] Python instruction patterns
33+
- [x] Docker/container patterns
34+
- [x] Testing framework patterns
35+
- [x] Makefile patterns
36+
- [x] Core copilot instruction patterns
37+
38+
### Step 6: Verification Framework
39+
- [x] Test execution commands
40+
- [x] Git operation sequences
41+
- [x] Error detection patterns
42+
- [x] Success validation criteria
43+
44+
## Phase 3: Testing and Refinement
45+
46+
### Step 7: Prompt Validation
47+
- [x] Dry-run simulation
48+
- [x] Test against current state
49+
- [x] Verify all file paths and commands
50+
- [x] Check instruction file syntax
51+
52+
### Step 8: Documentation
53+
- [x] Usage instructions
54+
- [x] Troubleshooting guide
55+
- [x] Example scenarios
56+
- [x] Maintenance procedures
57+
58+
### Step 9: Integration
59+
- [x] Place prompt in `.github/prompts/`
60+
- [x] Update project documentation
61+
- [x] Create usage examples
62+
- [x] Document for future maintainers
63+
64+
## Detailed Task Breakdown
65+
66+
### Task 1: Workflow Extraction
67+
**Inputs**:
68+
- Git commit 07dcdbd changes
69+
- `.devplanning/prompt-improvements-2025-09-14/` analysis
70+
- Current instruction file state
71+
72+
**Process**:
73+
1. Map each instruction file change to improvement pattern
74+
2. Document the decision logic for file selection
75+
3. Extract the exact text replacement patterns used
76+
4. Identify the verification commands executed
77+
78+
**Outputs**:
79+
- Workflow sequence document
80+
- Decision matrix for file updates
81+
- Template patterns for common changes
82+
83+
### Task 2: Pattern Codification
84+
**Inputs**:
85+
- 14 improvement patterns from determined-issues.md
86+
- Instruction file mapping logic
87+
- uv-first implementation examples
88+
89+
**Process**:
90+
1. Convert each pattern into prompt instructions
91+
2. Create conditional logic for pattern application
92+
3. Define file-specific customization rules
93+
4. Build verification checkpoints
94+
95+
**Outputs**:
96+
- Pattern application rules
97+
- File-specific instruction templates
98+
- Verification command sequences
99+
100+
### Task 3: Prompt Assembly
101+
**Inputs**:
102+
- Workflow sequence
103+
- Pattern application rules
104+
- Verification framework
105+
- Error handling strategies
106+
107+
**Process**:
108+
1. Structure main prompt sections
109+
2. Integrate decision logic
110+
3. Add verification checkpoints
111+
4. Include error recovery procedures
112+
113+
**Outputs**:
114+
- Complete prompt file
115+
- Usage documentation
116+
- Test validation plan
117+
118+
## Success Criteria Checklist
119+
120+
### Functional Completeness
121+
- [ ] Prompt recreates exact changes from commit 07dcdbd
122+
- [ ] All 14 improvement patterns are codified
123+
- [ ] File mapping logic is comprehensive
124+
- [ ] Verification steps are complete
125+
126+
### Technical Quality
127+
- [ ] All file paths are correct
128+
- [ ] Command sequences are validated
129+
- [ ] Error handling is robust
130+
- [ ] Git operations are safe
131+
132+
### Usability
133+
- [ ] Clear step-by-step instructions
134+
- [ ] Progress reporting is informative
135+
- [ ] Error messages are actionable
136+
- [ ] Documentation is comprehensive
137+
138+
### Maintainability
139+
- [ ] Prompt structure is modular
140+
- [ ] Easy to extend with new patterns
141+
- [ ] Version tracking is maintained
142+
- [ ] Future compatibility is ensured
143+
144+
## Timeline Estimate
145+
- Phase 1: 30 minutes (analysis and planning)
146+
- Phase 2: 45 minutes (prompt development)
147+
- Phase 3: 15 minutes (testing and refinement)
148+
- **Total**: ~90 minutes
149+
150+
## Dependencies
151+
- Access to current instruction files
152+
- Understanding of git workflow
153+
- Knowledge of uv command patterns
154+
- Test suite availability
155+
156+
## Risk Mitigation
157+
1. **Pattern Accuracy**: Cross-reference with actual changes made
158+
2. **File Conflicts**: Include backup/rollback procedures
159+
3. **Command Errors**: Validate all shell commands before inclusion
160+
4. **Version Tracking**: Ensure VERSION file logic is correct

0 commit comments

Comments
 (0)