78 lines
3.3 KiB
Markdown
78 lines
3.3 KiB
Markdown
---
|
|
name: yg-rules-output
|
|
description: Maintain the YG-Rules rule generation output system. Use when working on tasks that generate, inspect, validate, or modify rule task outputs, including output/rules-{task_id}/ folders, Excel .xlsx rule lists, Markdown .md reports, task status JSON metadata, SQL columns, and related Flask API responses.
|
|
---
|
|
|
|
# YG-Rules Output
|
|
|
|
## Overview
|
|
|
|
Use this skill to keep the YG-Rules output pipeline consistent: one generation task produces one task folder containing an Excel workbook and a Markdown report derived from the same rule rows.
|
|
|
|
The implementation lives primarily in `app/utils/rule_generation.py`, with API exposure in `app/routes/rules.py` and regression coverage in `tests/test_rule_generation.py`.
|
|
|
|
## Output Contract
|
|
|
|
Each task must write files under a dedicated directory:
|
|
|
|
```text
|
|
output/
|
|
rules-{task_id}/
|
|
rules-{task_id}.xlsx
|
|
rules-{task_id}.md
|
|
tasks/
|
|
{task_id}.json
|
|
```
|
|
|
|
Task state should expose both compatibility fields and grouped file metadata:
|
|
|
|
```json
|
|
{
|
|
"output_dir": "output/rules-{task_id}",
|
|
"output_file": "output/rules-{task_id}/rules-{task_id}.xlsx",
|
|
"markdown_file": "output/rules-{task_id}/rules-{task_id}.md",
|
|
"files": {
|
|
"excel": "output/rules-{task_id}/rules-{task_id}.xlsx",
|
|
"markdown": "output/rules-{task_id}/rules-{task_id}.md"
|
|
},
|
|
"markdown_error": null
|
|
}
|
|
```
|
|
|
|
Keep `output_file` and `markdown_file` for existing callers. Add new file types under `files`.
|
|
|
|
## Workflow
|
|
|
|
1. Inspect `RuleGenerationService.start()` to confirm task paths and state metadata.
|
|
2. Inspect `_run_task()` to confirm Excel write failures and Markdown write failures are handled independently.
|
|
3. Inspect `_build_rule_rows()` before changing Excel or Markdown fields. Excel and Markdown must consume this shared row model, not rebuild fields separately.
|
|
4. Update `_write_excel()` only for workbook-specific formatting.
|
|
5. Update `_write_markdown()` only for Markdown layout and grouping.
|
|
6. Update `/api/rules/generate` response when task metadata changes.
|
|
7. Add or update regression tests in `tests/test_rule_generation.py`.
|
|
8. Run `python -m pytest tests\test_rule_generation.py`.
|
|
|
|
## Design Rules
|
|
|
|
- Markdown content must follow actual generated rule rows, especially `risk_domain`; do not hardcode demo categories.
|
|
- Excel and Markdown must stay sibling files in the same task output directory.
|
|
- Markdown generation must not overwrite or invalidate a successful Excel workbook.
|
|
- A Markdown failure should set `markdown_error` and leave task status `done` if Excel generation succeeded.
|
|
- A zero-rule task may still write empty Excel and Markdown artifacts, but status should reflect the existing failed/no-rules behavior.
|
|
- SQL output belongs in both Excel and Markdown only when `create_sql` is enabled.
|
|
|
|
## References
|
|
|
|
- Read `references/output-contract.md` before changing task paths, task state, API response fields, or output file naming.
|
|
- Read `references/markdown-format.md` before changing Markdown structure or section names.
|
|
|
|
## Scripts
|
|
|
|
Use `scripts/validate_task_output.py` to validate a generated task directory:
|
|
|
|
```powershell
|
|
python skill\yg-rules-output\scripts\validate_task_output.py output\rules-20260422-171345-55c6e1
|
|
```
|
|
|
|
The script checks for sibling `.xlsx` and `.md` files, matching basenames, and basic Markdown structure.
|