---
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.