---
name: flawed-skill
description: Processes files via arguments, extracts key sections, applies transformations, and generates a summary report. Use when transforming file contents according to predefined patterns.
argument-hint: "file paths or patterns to process"
user-invocable: true
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
---

This skill processes files provided via `$ARGUMENTS`, extracts and transforms sections, then generates a formatted output report.

Refer to `unused-reference.md` for output formatting standards.

> **Stop after each stage** — validate results with the developer before proceeding.

0. **Understand inputs** (developer reviews)
   - What specific files are being processed? (Provide file paths or patterns)
   - What transformation rules should apply? (e.g., reformat headers, extract metadata, apply linting rules)
   - Provide examples of input → expected output
   - Confirm understanding and approve before proceeding to Stage 1

1. **Gather inputs** (agent executes)
   - **Validate arguments**: If `$ARGUMENTS` is empty, stop and prompt developer for file paths
   - **Read files**: Read each file specified in `$ARGUMENTS`
   - **Validate access**: If any file doesn't exist or isn't readable, report error with filename and stop
   - **Parse sections**: Identify key sections based on the transformation rules defined in Stage 0
   - **Report findings**: List all files found, total sections identified, any parsing issues

2. **Process and transform** (agent executes, developer reviews)
   - **Apply transformations**: For each section, apply the specific transformation rules from Stage 0
   - **Error recovery**: If a transformation fails on one file, log the error, continue to next file, do NOT stop
   - **Track changes**: Record which sections were transformed and which failed
   - **Write output**: Save transformed files to the project directory, preserving original filenames with `.transformed` suffix
   - **Summary**: Report count of [files processed, sections transformed, errors encountered, files with warnings]
   - **Developer review**: Developer verifies output before Stage 3 proceeds

3. **Final report** (agent executes)
   - **Generate summary document**: Create markdown file named `transformation-report.md` containing:
     - List of transformed files
     - Count of sections modified per file
     - Any errors or warnings encountered
     - Timestamp of execution
   - **Console output**: Print concise summary (1-2 sentences) to console
   - **Completion status**: Report success/partial-success/failure based on error count

---

## When to Use This Skill

| Goal | Use This Skill | Not This Skill |
|------|---|---|
| Generate structure from raw/crude notes | flesh-out | |
| Polish existing documents (language, clarity, structure) | review-steps | |
| Critique document substance and arguments | strong-edit | |
| Apply defined, mechanical transformations to files | **flawed-skill** | |
| Optimize document for AI agent consumption | agent-optimize | |

Use **flawed-skill** when you have:
- Specific transformation rules (not vague patterns)
- Input/output examples for clarity
- Files that need mechanical changes applied consistently
- A need to track what was transformed and report errors

---

See `responsibilities.md` for the full agent/developer ownership matrix.