home / skills / atman-33 / skills / detailed-design-parser

detailed-design-parser skill

safe

/skills/openspec/detailed-design-parser

This skill parses detailed-design.md files to extract and format file-specific changes into a detailed-design-by-file.md for easy copying.

npx playbooks add skill atman-33/skills --skill detailed-design-parser

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1005 B

---
name: detailed-design-parser
description: Parses detailed-design.md files to extract and format file-specific changes for easier copying. Use this skill when the user wants to generate a `detailed-design-by-file.md` from a `detailed-design.md` file.
metadata:
  short-description: Parse detailed-design.md for file changes
---

# Detailed Design Parser

This skill helps in parsing `detailed-design.md` files to extract code changes and format them into a `detailed-design-by-file.md` file. This is useful for copying file contents to other applications.

## Usage

1.  Identify the `detailed-design.md` file path. It is usually located at `openspec/changes/<openspec_id>/detailed-design.md`.
2.  Run the `parse_design.py` script with the path to the `detailed-design.md` file.

## Script

The script `scripts/parse_design.py` takes the input file path as an argument and generates the output file in the same directory.

```bash
python {path}/scripts/parse_design.py <path_to_detailed_design_md>
```

Overview

This skill parses detailed-design.md files and produces a file-centric view of proposed changes, formatted as detailed-design-by-file.md for easy copying. It extracts code snippets, file paths, and change blocks and organizes them by target file so reviewers and implementers can quickly apply edits. Use it when you need a clear, copy-ready breakdown of design changes per file.

How this skill works

The parser scans the detailed-design.md for labeled change sections and code fences, identifies the target file paths, and groups snippets under those file headers. It then writes a detailed-design-by-file.md alongside the source file with one entry per target file containing the relevant change blocks. The script is invoked with the path to the detailed-design.md and emits the output in the same directory.

When to use it

You have a detailed-design.md with multiple file-specific change blocks and need a copy-ready per-file summary.
Preparing patches or PRs and want to paste exact file contents into editors or web interfaces.
Onboarding reviewers who prefer seeing changes grouped by file instead of linear design prose.
Automating a handoff from design authoring to implementation tasks.
Extracting code snippets from long design documents for offline editing.

Best practices

Ensure each change block in detailed-design.md clearly labels the target file path to improve detection accuracy.
Use fenced code blocks for snippets and include minimal context lines for clarity.
Run the parser from the repository root or provide an absolute path to avoid path resolution issues.
Review the generated detailed-design-by-file.md for ambiguous or overlapping change blocks before applying edits.
Keep change blocks small and focused to make the by-file output easier to use.

Example use cases

Convert a multi-file design doc into individual file edits that can be pasted into a web-based code editor.
Create a one-file-per-section checklist for implementers to track which files need modification.
Speed up review by giving reviewers a per-file diff-style view derived from design prose.
Feed the by-file output into automation that creates PRs or applies patches programmatically.

FAQ

What input does the script expect?

It expects a detailed-design.md containing labeled change sections and fenced code blocks; file paths should be present so the parser can group snippets correctly.

Where is the output written?

The generated detailed-design-by-file.md is written to the same directory as the source detailed-design.md file.