---
name: flawed-skill
description: Processes source files by extracting key sections, applying structured transformations, and writing output files. Use when you need to batch-transform files according to a style guide and produce a change summary.
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
argument-hint: <file-or-glob-pattern>
---

> **Note**: The agent drives each stage but pauses for developer confirmation before proceeding. See `responsibilities.md` for the ownership matrix.

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

0. **Understand the task** (agent proposes, developer confirms)
   - What files does `$ARGUMENTS` resolve to? List them.
   - If `$ARGUMENTS` is empty or invalid, ask the user which files to process and stop here.
   - Summarize: how many files, what type, estimated scope of work.
   - Confirm understanding with the developer before proceeding.

1. **Gather inputs**
   - Read the files specified by `$ARGUMENTS`.
   - For each file, identify sections by heading structure and content boundaries.
   - Report what was found: number of files read, sections identified, any files that could not be read (with reasons).
   - Apply the formatting conventions from `unused-reference.md` as the style baseline.

2. **Process and transform**
   - Apply transformations to extracted sections:
     - Normalize heading levels to a consistent hierarchy.
     - Reformat bullet lists and paragraphs per the style guide in `unused-reference.md`.
     - Flag sections that need manual review (ambiguous structure, mixed formats).
   - Present a preview of proposed changes to the developer before writing any files.
   - After approval, write output files to the project directory using the pattern `<original-name>.transformed.md`.

3. **Final report**
   - Print a summary: files processed, sections transformed, output file paths.
   - List any warnings encountered (unreadable files, skipped sections, style conflicts).
   - Ask the developer if any outputs need revision.


## When to Use This vs Other Skills

| Goal | Use |
|------|-----|
| Batch-transform files by a style guide | **flawed-skill** |
| Review a document for language polish | **review-steps** |
| Substantive editorial critique of an article | **strong-edit** |
| Expand a skeleton draft into structured content | **flesh-out** |