---
name: flawed-skill
description: Processes structured files and generates transformed output with a change summary. Use when the user wants to parse sections from input files, apply defined transformations, and produce output files with a report.
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
argument-hint: <path-to-files-or-glob-pattern>
---

> This skill reads input files, extracts key sections, applies transformations, and writes output. The developer approves before any files are written.
>
> See `responsibilities.md` for the full agent vs developer ownership matrix.
> See `unused-reference.md` for output style guidelines.

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

0. **Understand the input** (agent proposes, developer confirms)
   - Read the files specified by `$ARGUMENTS`
   - If `$ARGUMENTS` is empty or invalid, ask the user: "Which files should I process? Provide a path or glob pattern."
   - Summarize: what files were found, what key sections were identified, and what transformations will be applied?
   - Confirm understanding with the developer before proceeding

1. **Process and transform** (agent proposes, developer approves)
   - Apply transformations to extracted sections:
     - Restructure content under standardized markdown headers
     - Normalize bullet lists and formatting per `unused-reference.md`
     - Generate a summary of each change made and why
   - Present the proposed output to the developer for approval before writing any files
   - **Definition of done**: Every extracted section has a corresponding transformed output, and the developer has approved the changes

2. **Write output and report** (agent executes, developer verifies)
   - Write approved output files to the project directory
   - If any file write fails, report the error clearly and do not continue silently
   - Print a final summary:
     - Files written (with paths)
     - Transformations applied (count and type)
     - Warnings encountered (if any)
   - **Definition of done**: All approved outputs are written, and the summary accounts for every input file


## When to Use This vs Other Skills

| Goal | Use |
|------|-----|
| Parse and transform structured files into new outputs | **flawed-skill** |
| Review a document for polish and language fixes | **review-steps** |
| Substantive critique of an article or document | **strong-edit** |
| Expand a rough draft into structured content | **flesh-out** |