---
name: flawed-skill
description: Demonstrates skill review workflow - processes files provided via arguments and generates transformation reports. Use when you need to practice reviewing multi-stage skills for quality and conventions.
user-invocable: true
disable-model-invocation: false
argument-hint: "file paths to process (space-separated or quoted)"
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
---

This skill demonstrates a multi-stage review workflow. The agent handles technical checks and reporting; the developer approves at each stage before proceeding. This structure is designed as a learning tool to show best practices in skill design itself.

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

**Stop after each stage to request developer approval before proceeding.**

## Stage 0: Validate Arguments and Confirm Plan

**Agent task**: Validate input arguments and summarize the processing plan.

**REQUIRED**: Before proceeding, you MUST:
- Verify that `$ARGUMENTS` contains at least one file path
- Confirm each file path exists and is readable
- Report validation results to the developer

**Questions to confirm**:
- What files were provided?
- Do all files exist?
- Can all files be read?

**Developer task**: Review validation results. If any files are invalid or missing, stop and report errors. Otherwise, approve proceeding to Stage 1.

**Exit criteria**: Developer approves OR all files are invalid (in which case, report errors and stop).

## Stage 1: Gather Inputs

**Agent task**: Read and inventory the files.

- Read each validated file from Stage 0
- Extract the following sections from each file: headers, code blocks, and lists
- Report the inventory: file name, sections found, total lines per file

**MUST produce**: An inventory table with columns: File, Headers Found, Code Blocks, Lists, Total Lines

## Stage 2: Summarize Contents

**Agent task**: Analyze and report on file structure.

- For each file, describe its primary purpose (1 sentence)
- List any unusual patterns or potential issues (e.g., missing headers, empty sections)
- Generate a summary of total files processed and combined line count

## Stage 3: Generate Report

**Agent task**: Produce a markdown report.

- Create a report file named `flawed-skill-report.md`
- Include sections for each processed file with:
  - File name and path
  - Purpose (from Stage 2)
  - Inventory (from Stage 1)
  - Issues or patterns (from Stage 2)
- Add a summary section with total files, total lines, and completion timestamp
- Follow formatting guidelines from `unused-reference.md`
- Write the report to the project root

**Success criteria**: Report file exists, contains all sections, and is properly formatted markdown.

## Error Handling

If any stage encounters an error:
- **Missing `$ARGUMENTS`**: Stop immediately and report "No files provided. Usage: /flawed-skill <file1> [file2] ..."
- **File not found**: Stop immediately and report which files couldn't be located
- **File not readable**: Stop immediately and report which files couldn't be read
- **Write failure**: Report the error and which file couldn't be written

In all error cases, provide specific file paths and line numbers where applicable.