Skip to content

Commit 41b4118

Browse files
maxchereymaxcherey
committed
feat: Add code-to-spec workflow documentation
Add 4 workflow files for systematic codebase analysis and behavioral specification: - 01-init: Create initial behavioral analysis and extract reusable facts - 02-verify: Verify security controls, soft-deletes, timeouts, and audit logs - 03-upgrade: Enhance spec with new scenarios and industry best practices - 04-compare: Compare specifications and generate change reports Enables structured approach to documenting existing systems for rewrites. Signed-off-by: Max <[email protected]>
1 parent fa7d530 commit 41b4118

4 files changed

Lines changed: 371 additions & 0 deletions

File tree

‎workflows/code-to-spec-01-init.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
description: Analyze existing code and create behavioral specification
3+
---
4+
5+
# Code to Spec Workflow
6+
7+
This workflow helps analyze an existing codebase and create comprehensive behavioral documentation for rewriting in a new technology stack.
8+
9+
## Steps
10+
11+
### 1. Review the Target Project
12+
13+
Review the specified project codebase to understand its structure, components, and overall architecture.
14+
15+
### 2. Create Behavioral Analysis
16+
17+
Create a complete behavioral analysis in `code-to-spec/ORIG_BEHAVIOR.md` that describes:
18+
- All supported scenarios (API calls, async jobs, etc.)
19+
- Primary execution paths
20+
- Error handling paths
21+
- Use the format that best describes each scenario type
22+
23+
### 3. Identify Rewrite Requirements
24+
25+
Document everything needed for complete rewriting using new technology:
26+
- Supported scenarios and use cases
27+
- Side effects and state changes
28+
- API contracts (inbound)
29+
- Database schemas and access patterns
30+
- Outbound API communications
31+
- Events and event handling
32+
- Audit logs and logging patterns
33+
34+
### 4. Extract Reusable Facts
35+
36+
For every behavioral fact observed:
37+
- Determine if it's a reusable pattern that maps to `code-to-spec/FACTS_TAXONOMY.md`
38+
- Document it in `code-to-spec/ORIG_FACTS`
39+
- Assign a unique identifier (e.g., F01.123)
40+
- Reference these facts in `code-to-spec/ORIG_BEHAVIOR.md` using [F01.123] notation
41+
42+
This enables mapping facts to new technology stack implementations (e.g., changing DB access checks, logging approaches, etc.)
43+
44+
### 5. Validate Scenario Details
45+
46+
For every scenario in `code-to-spec/ORIG_BEHAVIOR.md`, verify and document:
47+
48+
**Security & Access:**
49+
- ✓ Triple-check all API role checks
50+
- ✓ Triple-check all DB access checks
51+
- ✓ Verify license checks
52+
- ✓ Verify quota checks
53+
- ✓ Document all conditional access logic
54+
55+
**Data Handling:**
56+
- ✓ Double-check soft-deleted item handling (used or excluded)
57+
- ✓ Clarify all edge cases and corner scenarios
58+
59+
**External Communications:**
60+
- ✓ Double-check all outbound communications are described:
61+
- Synchronous vs asynchronous
62+
- Timeout configurations
63+
- Error management strategies
64+
- ✓ Document all timeouts and limitations with fact references
65+
66+
**Observability:**
67+
- ✓ Double-check all events are mentioned
68+
- ✓ Double-check all audit logs are documented
69+
- ✓ Ensure logging is covered for all scenarios
70+
71+
### 6. Final Review
72+
73+
Review `code-to-spec/ORIG_BEHAVIOR.md` and `code-to-spec/ORIG_FACTS` for:
74+
- Completeness of all scenarios
75+
- Accuracy of security checks
76+
- Proper fact referencing
77+
- Clear error path documentation
78+
- Complete external dependency documentation
79+
80+
## Output Files
81+
82+
All files are created in the `code-to-spec/` directory:
83+
84+
- `code-to-spec/ORIG_BEHAVIOR.md` - Complete behavioral specification with fact references
85+
- `code-to-spec/ORIG_FACTS` - Extracted reusable behavioral facts with taxonomy mapping
86+
87+
## Reference Files
88+
89+
- `code-to-spec/FACTS_TAXONOMY.md` - Taxonomy of reusable behavioral facts (should exist before running workflow)

‎workflows/code-to-spec-02-verify.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
description: Verify and refine original behavioral specification
3+
---
4+
5+
# Verify Original Spec Workflow
6+
7+
This workflow performs critical verification and refinement of the `code-to-spec/ORIG_BEHAVIOR.md` and `code-to-spec/ORIG_FACTS` files created by the code-to-spec workflow.
8+
9+
**IMPORTANT:** Make ONLY critical changes and improvements as specified below. DO NOT make style changes or format changes.
10+
11+
## Prerequisites
12+
13+
- `code-to-spec/ORIG_BEHAVIOR.md` must exist
14+
- `code-to-spec/ORIG_FACTS` must exist
15+
16+
## Steps
17+
18+
### 1. Review All Scenarios
19+
20+
For every scenario in `code-to-spec/ORIG_BEHAVIOR.md`:
21+
22+
**Clarify Details:**
23+
- ✓ Clarify all tiny details of the scenarios
24+
- ✓ Put double attention on scenarios correctness
25+
26+
### 2. Triple-Check Security & Access Controls
27+
28+
**CRITICAL FOCUS AREA** - For every scenario:
29+
30+
- ✓ **Triple-check** all API ROLE checks
31+
- ✓ **Triple-check** all DB access checks
32+
- ✓ **Triple-check** license checks
33+
- ✓ **Triple-check** quota checks
34+
- ✓ **Triple-check** all other conditional checks
35+
36+
This is the key focus of this verification step.
37+
38+
### 3. Verify Soft-Delete Handling
39+
40+
For every scenario:
41+
- ✓ **Double-check** that soft-deleted items handling is properly mentioned
42+
- ✓ Explicitly state whether soft-deleted items are used or not used in each scenario
43+
44+
### 4. Verify Outbound Communications
45+
46+
For every scenario:
47+
- ✓ **Double-check** all outbound communications are well described:
48+
- Synchronous vs asynchronous
49+
- Timeout configurations
50+
- Error management strategies
51+
52+
### 5. Verify Timeouts and Limitations
53+
54+
For every scenario:
55+
- ✓ **Double-check** all timeouts are mentioned
56+
- ✓ **Double-check** all limitations are mentioned
57+
- ✓ Ensure proper references to facts are included
58+
59+
### 6. Verify Events and Audit Logs
60+
61+
For every scenario:
62+
- ✓ **Double-check** all events are mentioned
63+
- ✓ **Double-check** all audit logs are mentioned
64+
65+
### 7. Update Files
66+
67+
Update the following files with critical improvements only:
68+
- `code-to-spec/ORIG_BEHAVIOR.md`
69+
- `code-to-spec/ORIG_FACTS`
70+
71+
**Remember:** Make ONLY critical changes and improvements. DO NOT make style or format changes.
72+
73+
## Output
74+
75+
Updated versions of:
76+
- `code-to-spec/ORIG_BEHAVIOR.md` - with verified and refined scenarios
77+
- `code-to-spec/ORIG_FACTS` - with any additional facts discovered during verification

‎workflows/code-to-spec-03-upgrade.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
description: Upgrade original spec with improvements and new scenarios
3+
---
4+
5+
# Spec Upgrade Workflow
6+
7+
This workflow upgrades the original behavioral specification by incorporating improvements, suggesting enhancements, and adding new cutting-edge scenarios.
8+
9+
## Prerequisites
10+
11+
- `code-to-spec/ORIG_BEHAVIOR.md` must exist
12+
- `code-to-spec/ORIG_FACTS` must exist
13+
14+
## Steps
15+
16+
### 1. Create New Specification
17+
18+
Copy `code-to-spec/ORIG_BEHAVIOR.md` to `code-to-spec/NEW_BEHAVIOR.md`
19+
20+
### 2. Incorporate Direct Proposals
21+
22+
Incorporate any direct proposals or improvements suggested by the user into `code-to-spec/NEW_BEHAVIOR.md`
23+
24+
### 3. Review for Gaps
25+
26+
Review `code-to-spec/NEW_BEHAVIOR.md` for potential gaps and suggest improvements:
27+
- Missing scenarios
28+
- Possible new APIs
29+
- Enhanced error handling
30+
- Better integration patterns
31+
32+
### 4. Suggest Cutting-Edge Patterns
33+
34+
For the given domain, suggest:
35+
- Cutting-edge industry patterns
36+
- Modern features
37+
- Advanced scenarios
38+
- Best practices
39+
40+
### 5. Mark New Content
41+
42+
**CRITICAL:** For every NEW scenario or step, put mandatory **[NEW]** prefix!
43+
44+
This allows for easy diff comparison later.
45+
46+
## Structure Requirements
47+
48+
**IMPORTANT:**
49+
- KEEP ORIG_BEHAVIOR structure intact
50+
- CREATE NEW scenarios at the END of the file
51+
- CREATE NEW steps INLINE within existing scenarios
52+
- Structure must allow for easy diff comparison later
53+
54+
## Output Files
55+
56+
- `code-to-spec/NEW_BEHAVIOR.md` - Upgraded behavioral specification with [NEW] markers
57+
- `code-to-spec/ORIG_FACTS` - May be updated with new facts (mark new facts appropriately)
58+
59+
## Example Marking
60+
61+
```markdown
62+
### Existing Scenario
63+
1. Existing step
64+
2. [NEW] New step added
65+
3. Existing step
66+
67+
### [NEW] Completely New Scenario
68+
1. [NEW] First step of new scenario
69+
2. [NEW] Second step of new scenario
70+
```

‎workflows/code-to-spec-04-compare.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
description: Compare specifications and generate change report
3+
---
4+
5+
# Compare Specs Workflow
6+
7+
This workflow compares two versions of behavioral specifications (ORIG vs NEW) and generates a comprehensive change report with importance ratings.
8+
9+
## Prerequisites
10+
11+
- `code-to-spec/ORIG_BEHAVIOR.md` must exist
12+
- `code-to-spec/NEW_BEHAVIOR.md` must exist
13+
- `code-to-spec/ORIG_FACTS` must exist
14+
15+
## Steps
16+
17+
### 1. Compare Specifications
18+
19+
Compare the provided specifications:
20+
- BEHAVIOR files (ORIG vs NEW)
21+
- FACTS files
22+
23+
### 2. Analyze API Changes
24+
25+
Put special attention to:
26+
- API changes (endpoints, parameters, responses)
27+
- Scenario changes (new, modified, removed)
28+
- Exact FACTS changes
29+
30+
### 3. Triple-Check Security & Access Controls
31+
32+
**CRITICAL FOCUS AREA:**
33+
34+
- ✓ **Triple-check** all API ROLE checks changes
35+
- ✓ **Triple-check** all DB access check changes
36+
- ✓ **Triple-check** license checks changes
37+
- ✓ **Triple-check** quota checks changes
38+
- ✓ **Triple-check** all other conditional checks changes
39+
40+
This is the key focus of comparison.
41+
42+
### 4. Verify Soft-Delete Handling Changes
43+
44+
- ✓ **Double-check** soft-deleted items handling changes
45+
- ✓ Verify proper documentation of soft-deleted items usage in every scenario
46+
47+
### 5. Verify Outbound Communications Changes
48+
49+
- ✓ **Double-check** all outbound communications changes:
50+
- Synchronous vs asynchronous
51+
- Timeout configurations
52+
- Error management strategies
53+
54+
### 6. Verify Timeouts and Limitations Changes
55+
56+
- ✓ **Double-check** all timeout changes
57+
- ✓ **Double-check** all limitation changes
58+
- ✓ Verify proper references to facts
59+
60+
### 7. Verify Events and Audit Logs Changes
61+
62+
- ✓ **Double-check** all event changes
63+
- ✓ **Double-check** all audit log changes
64+
65+
### 8. Generate Changes Report
66+
67+
Create `code-to-spec/CHANGES.md` with comprehensive change descriptions.
68+
69+
### 9. Group Similar Changes
70+
71+
- Group similar changes together
72+
- If broad change detected, create separate chapter
73+
- Mention all affected places for grouped changes
74+
75+
### 10. Document Individual Changes
76+
77+
Keep individual changes as separate items when they don't fit into groups.
78+
79+
### 11. Assign Importance Ratings
80+
81+
For every change, assign importance factor:
82+
83+
**MAJOR Changes:**
84+
- Any access control changes
85+
- DB access check changes
86+
- Configuration parameter changes
87+
- API incompatible changes (breaking changes)
88+
89+
**MODERATE Changes:**
90+
- Likely compatible changes
91+
- New API parameters (backward compatible)
92+
- New error types
93+
- Config structure changes (non-drastic)
94+
95+
**MINOR Changes:**
96+
- Other behavioral changes
97+
- Documentation improvements
98+
- Non-breaking enhancements
99+
100+
## Output File
101+
102+
`code-to-spec/CHANGES.md` with structure:
103+
104+
```markdown
105+
# Changes Report
106+
107+
## MAJOR Changes
108+
109+
### [Group Name] (if applicable)
110+
- Change description
111+
- Affected locations: ...
112+
113+
### Individual MAJOR Change
114+
- Change description
115+
- Impact: ...
116+
117+
## MODERATE Changes
118+
119+
### [Group Name] (if applicable)
120+
- Change description
121+
- Affected locations: ...
122+
123+
## MINOR Changes
124+
125+
...
126+
```
127+
128+
## Change Report Format
129+
130+
Each change should include:
131+
- Clear description
132+
- Importance rating (MAJOR/MODERATE/MINOR)
133+
- Affected components/scenarios
134+
- Impact assessment
135+
- References to specific facts if applicable

0 commit comments

Comments
 (0)