YG-Rules/skill/yg-rules-output/SKILL.md

name, description

name	description
yg-rules-output	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:

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:

{
  "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:

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.