documentation: AI specs, data format docs, Russian README
This commit is contained in:
catarrh committed
1 parent
4a1e22d68b
commit
84c8ceb172
8 files changed
+2662
-7
No files matched your search
@@ -0,0 +1,235 @@
|
||||
# Working Policies for AI Agents
|
||||
|
||||
## Data Modification Rules
|
||||
|
||||
### Never Overwrite Existing Content
|
||||
- **CRITICAL**: Never overwrite existing `life.text` fields in lives entries
|
||||
- Enrichment pipeline only fills empty entries
|
||||
- If a target already has content, classify as `already-filled` and skip
|
||||
|
||||
### File Modification Permissions
|
||||
- **Allowed**: Adding new life.text to empty entries
|
||||
- **Allowed**: Adding manual fixes to `enrich-lives.ts` MANUAl_FIXES
|
||||
- **Allowed**: Correcting menaion-bundle.json for CId date corrections
|
||||
- **Forbidden**: Modifying existing life.text content
|
||||
- **Forbidden**: Deleting or renaming CIds without proper validation
|
||||
- **Forbidden**: Changing JSON structure without updating related code
|
||||
|
||||
## Validation Requirements
|
||||
|
||||
### Pre-Commit Checklist
|
||||
All changes must pass all three checks:
|
||||
|
||||
```bash
|
||||
# 1. Data validation
|
||||
npx tsx scripts/validate-data.ts
|
||||
# Expected: "All files valid!" or specific error count
|
||||
|
||||
# 2. Type safety
|
||||
npx tsc --noEmit
|
||||
# Expected: No TypeScript errors
|
||||
|
||||
# 3. Build verification
|
||||
npm run build
|
||||
# Expected: Successful build with reasonable bundle sizes
|
||||
```
|
||||
|
||||
### When to Stop
|
||||
- Stop immediately if any validation fails
|
||||
- Fix errors before proceeding
|
||||
- Address TypeScript compilation issues
|
||||
- Check build output for unexpected size changes
|
||||
|
||||
## Commit Message Standards
|
||||
|
||||
### Format Conventions
|
||||
|
||||
**Enrichment commits**:
|
||||
```
|
||||
enrich [N] more ru lives: [brief description]
|
||||
```
|
||||
|
||||
**Bundle fix commits**:
|
||||
```
|
||||
fix bundle: move [saint] from [date1] to [date2]
|
||||
```
|
||||
|
||||
**Script updates**:
|
||||
```
|
||||
update [script name]: [brief description]
|
||||
```
|
||||
|
||||
**General guidance**:
|
||||
- Be specific about what changed
|
||||
- Reference specific CIds or dates when applicable
|
||||
- Keep messages concise but descriptive
|
||||
- Reference recent commits for style
|
||||
|
||||
## File Change Guidelines
|
||||
|
||||
### Static Data Files
|
||||
- **Tracked**: `static/data/` directory (all JSON files tracked)
|
||||
- **Not tracked**: `scripts/output/minei.json` (33MB generated file)
|
||||
- **Validate**: Always run validation after data changes
|
||||
|
||||
### Script Files
|
||||
- Maintain existing code patterns
|
||||
- Use existing helper functions when available
|
||||
- Update documentation in relevant markdown files
|
||||
|
||||
### Output Files
|
||||
- Generated files (`dist/`, `scripts/output/`) should not be committed
|
||||
- Only commit source code and data files
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
### TypeScript Requirements
|
||||
- Maintain strict typing
|
||||
- Follow existing code conventions
|
||||
- Add type annotations where appropriate
|
||||
- Use proper error handling
|
||||
|
||||
### Data Structure Integrity
|
||||
- Maintain CId naming conventions
|
||||
- Preserve JSON structure consistency
|
||||
- Ensure required fields are present (`name.nominative` in lives entries)
|
||||
|
||||
## Error Handling Protocols
|
||||
|
||||
### When Validation Fails
|
||||
1. Review error messages carefully
|
||||
2. Identify root cause (JSON syntax, missing fields, type issues)
|
||||
3. Fix the underlying problem
|
||||
4. Re-run validation until it passes
|
||||
5. Then proceed to type checking
|
||||
|
||||
### When TypeScript Fails
|
||||
1. Check for type mismatches in modified code
|
||||
2. Verify imports and exports
|
||||
3. Ensure all dependencies are properly declared
|
||||
4. Fix type errors
|
||||
5. Re-run tsc --noEmit
|
||||
|
||||
### When Build Fails
|
||||
1. Check console output for specific errors
|
||||
2. Verify data file integrity
|
||||
3. Check for import/export issues
|
||||
4. Resolve build errors before proceeding
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
### When Modifying Data Schemas
|
||||
- Update relevant documentation files (DATA_FORMAT.md, DATA_RUS.md)
|
||||
- Note any breaking changes or invariants
|
||||
- Update project README if structural changes
|
||||
|
||||
### When Adding New Scripts
|
||||
- Document the script's purpose and usage
|
||||
- Add NPM script entry if needed
|
||||
- Update project documentation as appropriate
|
||||
|
||||
## Common Operational Pitfalls
|
||||
|
||||
### Data Modification Risks
|
||||
- ⚠️ **Don't accidentally overwrite existing life.text** — Always check before writing
|
||||
- ⚠️ **Don't skip validation** — Always validate before committing
|
||||
- ⚠️ **Don't ignore build errors** — Build failures indicate real problems
|
||||
- ⚠️ **Don't commit generated files** — Avoid committing dist/ or output files
|
||||
|
||||
### Code Change Risks
|
||||
- ⚠️ **Don't break existing patterns** — Follow established code conventions
|
||||
- ⚠️ **Don't duplicate logic** — Use existing helper functions
|
||||
- ⚠️ **Don't ignore type safety** — Maintain TypeScript strict typing
|
||||
- ⚠️ **Don't make undocumented changes** — Update relevant documentation
|
||||
|
||||
### Commit Risks
|
||||
- ⚠️ **Don't commit without validation** — Ensure all checks pass
|
||||
- ⚠️ **Don't write vague commit messages** — Be specific about what changed
|
||||
- ⚠️ **Don't assume `static/data/` is excluded** — It's tracked, commit your changes
|
||||
|
||||
## Workflow for New Enrichment Work
|
||||
|
||||
### Before Starting
|
||||
1. Review existing MANUAL_FIXES in `enrich-lives.ts`
|
||||
2. Understand the current coverage status
|
||||
3. Identify which dates/cases you're targeting
|
||||
|
||||
### During Work
|
||||
1. Use dry runs first: `npx tsx scripts/enrich-lives.ts`
|
||||
2. Review the match report carefully
|
||||
3. Add MANUAL_FIXES only for problematic matches
|
||||
4. Re-run dry run until satisfied with results
|
||||
5. Only use `--write` when confident
|
||||
|
||||
### After Completion
|
||||
1. Verify file sizes are reasonable
|
||||
2. Check that collision appends are correct
|
||||
3. Run full validation suite
|
||||
4. Commit with descriptive message
|
||||
|
||||
## Quality Assurance Standards
|
||||
|
||||
### Coverage Tracking
|
||||
- Monitor coverage statistics: `1190/3046 lives with text`
|
||||
- Track unmatched count: currently 27 (floor for this data source)
|
||||
- Report changes in coverage when adding MANUAL_FIXES
|
||||
|
||||
### Content Verification
|
||||
- For collision targets, verify chapter counts
|
||||
- Check that first chapter being unheaded is expected behavior
|
||||
- Verify that life.text contains expected content for known CIds
|
||||
|
||||
### Consistency Checks
|
||||
- Ensure similar fixes follow the same pattern
|
||||
- Maintain consistency with existing MANUAL_FIXES format
|
||||
- Keep naming conventions consistent across all entries
|
||||
|
||||
## Quick Reference for Common Operations
|
||||
|
||||
### Adding a MANUAL_FIX
|
||||
```typescript
|
||||
const MANUAL_FIXES: Record<string, string> = {
|
||||
'MM-DD|distinctive-substring': 'CId',
|
||||
};
|
||||
```
|
||||
- Key format: `${date}|${substring}` → CId
|
||||
- Substring must be unique within that date
|
||||
- CId must be empty for the fix to have effect
|
||||
|
||||
### Running Enrichment
|
||||
```bash
|
||||
# Dry run
|
||||
npx tsx scripts/enrich-lives.ts
|
||||
|
||||
# Write changes
|
||||
npx tsx scripts/enrich-lives.ts --write
|
||||
|
||||
# Single month
|
||||
npx tsx scripts/enrich-lives.ts --month 01
|
||||
npx tsx scripts/enrich-lives.ts --write --month 01
|
||||
```
|
||||
|
||||
### Validating Data
|
||||
```bash
|
||||
# Main validator
|
||||
npx tsx scripts/validate-data.ts
|
||||
|
||||
# Period-specific validators
|
||||
npx tsx scripts/validate-menaion.ts
|
||||
npx tsx scripts/validate-triodion.ts
|
||||
```
|
||||
|
||||
### Quick Coverage Check
|
||||
```bash
|
||||
python3 -c "
|
||||
import json,glob,os
|
||||
total=has=0
|
||||
for fp in glob.glob('static/data/ru/lives/*.json'):
|
||||
data=json.load(open(fp))
|
||||
for cid,entry in data.items():
|
||||
total+=1
|
||||
if isinstance(entry.get('life'),dict) and entry.get('life',{}).get('text'):
|
||||
has+=1
|
||||
print(f'Coverage: {has}/{total} ({has*100//total}%) lives with text')
|
||||
"
|
||||
```
|
||||
Reference in new issue
Block a user