---
name: flawed-skill
description: Processes and transforms file contents based on specified patterns, extracting key sections and generating structured output with a summary report and warnings. Useful for automated document analysis, content extraction, and batch transformations.
argument-hint: "FILE_PATHS"
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
user-invocable: true
---

This skill processes files provided via `$ARGUMENTS`, extracts key sections based on defined patterns, applies transformations following a style guide, and generates a structured output report with warnings.

## Stage 0: Understanding and Approach Confirmation

**Agent responsibility:** Examine the provided files and propose a transformation strategy.

- Read the files specified in `$ARGUMENTS`
- Analyze their current structure (headers, sections, content types)
- Propose:
  - What sections will be extracted (e.g., headers, code blocks, metadata, paragraphs)
  - What transformations will be applied (e.g., reformatting, reorganization, filtering, deduplication)
  - Output location and filenames (default: `output/` directory)
  - Example of one transformed section

**Developer responsibility:** Review the proposed approach and approve before proceeding.

> **Stop here for developer review and approval before proceeding to Stage 1.**

---

## Stage 1: Validate Inputs and Plan Execution

**Agent responsibility:** Verify that all files exist and are readable. Handle missing inputs gracefully.

- Check if `$ARGUMENTS` was provided
  - If empty or missing, prompt the developer: "Please provide file paths as `$ARGUMENTS` (space-separated or comma-separated)"
  - Show example: `file1.md file2.md` or `path/to/file.txt,another_file.md`
- Verify each file exists and is readable
- Report findings:
  - ✅ Files found and readable (list them)
  - ❌ Files not found or inaccessible (list them with paths)

If any files are missing and cannot be processed, ask the developer if you should proceed with the readable files or stop.

**Developer responsibility:** Confirm validation results and approve proceeding to Stage 2.

> **Stop here to confirm inputs are valid before proceeding to Stage 2.**

---

## Stage 2: Extract and Transform Content

**Agent responsibility:** Apply the approved transformations from Stage 0.

- Read each valid file
- Extract key sections:
  - Markdown headers and their content
  - Code blocks with language identifiers
  - Metadata (YAML frontmatter, title blocks)
  - Paragraphs and lists
  - Table of contents if present
- Apply transformations:
  - **Reformatting:** Ensure consistent markdown syntax, header levels, spacing (per `unused-reference.md`)
  - **Reorganization:** Group related sections together, reorder by hierarchy
  - **Filtering:** Remove duplicates, condense repetitive content, prune empty sections
  - **Enhancement:** Add missing structure (e.g., headers for headerless sections)
- Track warnings for later reporting:
  - Malformed syntax (e.g., unclosed code blocks, broken headers)
  - Sections that were skipped due to parse errors
  - Files with encoding issues

**Developer responsibility:** Review extracted and transformed content samples. Approve final report generation.

> **Stop here to review extracted and transformed content before proceeding to Stage 3.**

---

## Stage 3: Generate Final Report and Output Artifacts

**Agent responsibility:** Produce output files and a summary report.

- Create `output/` directory if it does not exist
- Write transformed content to numbered files:
  - `output/file_1_transformed.md` (for first input file)
  - `output/file_2_transformed.md` (for second input file)
  - etc.
- Generate a summary report file: `output/SUMMARY.md`

**Summary report format:**

```
# Processing Summary

## Overview
- **Files processed:** [count]
- **Total sections extracted:** [count]
- **Transformations applied:** [list]
- **Total warnings:** [count]

## Files Processed
- file1.md → output/file_1_transformed.md (sections: 5)
- file2.md → output/file_2_transformed.md (sections: 3)

## Warnings
[If any; formatted as list with file name, line number, and issue]

Example:
- file1.md, line 12: Malformed header syntax (fixed)
- file2.md: One section skipped due to encoding error
```

**Developer responsibility:** Review final report and output files. Confirm processing is complete.

> **Skill complete.** All files processed and output written to `output/` directory.

---

## Error Handling and Edge Cases

| Scenario | Behavior |
|----------|----------|
| `$ARGUMENTS` is missing or empty | Prompt developer for file paths. Do not proceed without files. |
| File does not exist | Report the missing file. Ask developer whether to skip it or stop. |
| File is not readable | Report permission error and skip. Continue with other files. |
| Parse error in file | Record warning, skip that section, continue processing the file. |
| Write permission denied on `output/` | Report error with path. Suggest alternative location and exit. |
| No valid files to process | Report and exit without creating output directory. |

---

## Output Format

Following style guidelines from `unused-reference.md`:
- Use markdown headers (##) for sections
- Keep paragraphs short and readable
- Use bullet lists for enumeration and features
- Use code fences for examples and code blocks
- Maintain consistent spacing between sections