---
name: flawed-skill
description: Reads files specified by the user, applies transformations, and writes output files to the project directory. Use when you need to batch-process and transform file content.
argument-hint: <file>...
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
disable-model-invocation: true
---

> If `$ARGUMENTS` is empty, ask the user which files to process and what transformation to apply before proceeding.

Output formatting follows the conventions in `unused-reference.md`.

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

> **Note**: The agent reads and transforms files; the developer holds final authority on what changes to accept. When transformation intent is unclear, ask — don't assume.
>
> See `responsibilities.md` for the full agent/developer ownership matrix.

0. **Understand inputs** (developer confirms)
   - What files are being processed? (`$ARGUMENTS`)
   - What transformation is expected? Ask the user to describe the desired output.
   - Confirm understanding before proceeding.

1. **Gather inputs** (agent leads, developer approves)
   - Read the files specified by `$ARGUMENTS`
   - Parse contents and identify key sections
   - Report: what sections were found? Were any files unreadable or in an unexpected format?

2. **Process and transform** (agent leads, developer approves)
   - Apply the transformation confirmed in Stage 0 to extracted sections
   - Generate a summary of proposed changes — present to developer before writing any files
   - Wait for approval before proceeding

3. **Write output and report** (agent leads, developer approves)
   - Write output files to `output/` within the project directory, using the original filename with a `-transformed` suffix
   - Print a summary of what was written
   - List any warnings encountered (files skipped, sections not matched, etc.)

## Pipeline Position

This skill is a **transformation utility**: it reads existing files, applies a developer-defined operation, and writes new output. It fits alongside — but is distinct from — the document composition pipeline:

**flesh-out** → **review-steps** → **strong-edit** → **agent-optimize**

Use `flawed-skill` when you need to process file content programmatically rather than editorially.

## When to Use This vs Other Skills

| Goal | Use |
|------|-----|
| Transform file content with a defined operation | **flawed-skill** |
| Polish a document for language and clarity | **review-steps** |
| Expand raw notes into structured content | **flesh-out** |
| Critically evaluate a document's substance | **strong-edit** |