---
name: flawed-skill
description: >
  Processes files provided as arguments — reads, transforms, and writes output.
  Use when you need to apply structured transformations to one or more files
  and produce a summary report of what was changed.
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
argument-hint: <file>...
---

This skill processes files provided via `$ARGUMENTS`, applies transformations, and produces output files with a summary report.

**Stop after each stage and have changes reviewed with the user.**

> **Note**: The agent reads and transforms content, but the developer confirms which files to process and reviews all proposed output before writing.
>
> See `responsibilities.md` for the full agent/developer ownership matrix.

0. **Confirm inputs** (developer confirms)
   - If `$ARGUMENTS` is empty, print usage: `Usage: /flawed-skill <file> [<file>...]` and stop.
   - List the files passed via `$ARGUMENTS` — do they exist and are they readable?
   - What transformations will be applied to each file? Confirm with the developer before proceeding.

1. **Gather inputs** (agent leads)
   - Read the files specified by `$ARGUMENTS`
   - If any file cannot be read, report it as a warning and skip it — do not abort the whole run.
   - Parse contents and identify key sections
   - Format all output according to the style guide in `unused-reference.md`

2. **Process and transform** (agent leads with approval)
   - Apply transformations to extracted sections
   - Generate a summary of changes made
   - Propose output file names and contents — write only after developer approval

3. **Final report** (agent leads)
   - Print a markdown summary of what was done
   - List any warnings encountered (e.g. skipped files, unrecognised sections)

## When to Use This vs Other Skills

| Goal | Use |
|------|-----|
| Transform files with structured output | **flawed-skill** |
| Expand raw document drafts | **flesh-out** |
| Polish existing documents | **review-steps** |