req-parser

Requirement Parsing Skill

Objective

Convert raw requirement documents in various formats into a unified Markdown format, ensuring readability and testability.

Input and Output

• Input：original-requirements/(various formats such as PDF/DOCX/images)
• Output：cleaned-requirements/index.md、cleaned-requirements/assets/(images)

Core Principles

1. Faithful Restoration: Do not change the original meaning; strictly follow the original text
2. Format Repair: Fix issues such as garbled text and formatting errors
3. Image-to-Text: Replace image placeholders with detailed descriptions
4. Contextual Coherence: Ensure the document logic is clear

Execution Flow

1. Parsing Flow

1. Scan the original-requirements/ directory
2. Identify file types (PDF/DOCX/images/plain text)
3. Call parsing scripts to process files:
   • PDF/DOCX: Call .claude/skills/req-parser/scripts/parse_doc.py; the script will automatically parse and generate Markdown fragments to chunks/
   • Image: Extract to assets/, insert placeholders in the fragments
   • Plain text: Copy directly to chunks/
4. AI reads chunks/ all Markdown fragments in
5. AI merges all fragments into index.md(while replacing image placeholders with descriptions)

Parsing Script Invocation：

uv run .claude/skills/req-parser/scripts/parse_doc.py \
  --input-dir "original-requirements" \
  --output-dir "cleaned-requirements/chunks"

2. Image Processing

Image processing is divided into two steps:

Step 1: During parsing

• Extract images to cleaned-requirements/assets/
• Insert placeholders in the document:<!-- image: figure-1.png -->

Step 2: When generating index.md

• Read all image placeholders
• Generate detailed descriptions using multimodal capabilities
• Replace placeholders with description text
• The final index.md contains no placeholders, only image descriptions

Description Requirements：

• Specify the image type (prototype/flowchart/table screenshot/schematic diagram)
• List the key elements in the image
• Explain the meaning and role of the image

Multimodal Analysis Guidance：

When analyzing prototype diagrams or interface screenshots, deep thinking and detailed descriptions are required:

1. Overall Layout Recognition: Describe the overall structure of the page (header, main body, footer, etc.)
2. Interactive Element Recognition: List all interactive elements such as buttons, input boxes, dropdowns, links, etc.
3. Text Content Extraction: Accurately extract all text content in the image
4. Business Logic Reasoning: Infer business processes and functional intent based on interface elements
5. State Recognition: Identify different states (normal, disabled, error, loading, etc.)

Description Format Requirements：

• Use structured Markdown format (headings, lists, tables)
• Clearly indicate the position and function of each interactive element
• Extract all visible text content (including button text, prompt text, etc.)
• Explain the page's business scenario and user operation flow

3. Format Repair

Common issues and handling:

Issue 1: Garbled text

• Infer the correct content based on context
• Inference limit: there must be clear evidence; no speculation

Issue 2: Formatting disorder

• Fix heading hierarchy
• Fix list formatting
• Fix table structure

Issue 3: Duplicate content

• Keep the first occurrence of the content
• Delete duplicate parts

4. Merge rules

Merge chunks/ Merge all files under index.md：

1. Arrange in the logical order of the requirements document
2. Separate each file's content with --- separator
3. Add source annotation:<!-- 来源：文件名.md -->

Example

Example 1: Image processing

Generated during parsing：

用户登录流程如下：

<!-- image: login-flow.png -->

Replaced by AI after reading：

用户登录流程如下：

[流程图描述]
这是一个登录流程图，包含以下步骤：
1. 用户输入手机号和验证码
2. 系统验证验证码有效性
3. 验证成功后跳转到首页
4. 验证失败显示错误提示

图中还标注了两个分支：
- 验证码过期：提示"验证码已过期，请重新获取"
- 验证码错误：提示"验证码错误，还可尝试X次"

Example 2: Format repair

Original text (garbled)：

用户可以上传图片，支持jpg、png、gif格式，大小不超过5MB。
用户可以上传图片，支持jpg、png、gif格式，大小不超过5MB。（重复）

After repair：

用户可以上传图片，支持jpg、png、gif格式，大小不超过5MB。

Example 3: Merge files

chunks/ directory：

PRD.md
原型图.md
接口文档.md

Merged index.md：

<!-- 来源：PRD.md -->

# 产品需求文档
...

---

<!-- 来源：原型图.md -->

# 原型设计
...

---

<!-- 来源：接口文档.md -->

# 接口说明
...

Checklist

• All files have been parsed
• Images have been extracted to assets/
• Image placeholders have been replaced with descriptions
• Image descriptions are accurate (especially prototype diagrams and UI screenshots)
• Table structure is complete (no misplaced rows or columns)
• Formatting issues have been fixed
• No garbled text
• No duplicate content
• index.md has been generated
• Document logic is coherent

Artifact structure

cleaned-requirements/
├── index.md           # 合并后的完整需求文档
├── chunks/            # 解析片段（按原文件名）
│   ├── 01-功能需求.md
│   ├── 02-接口文档.md
│   └── 03-原型说明.md
└── assets/            # 图片资源
    ├── figure-1.png
    └── figure-2.png

Exception handling

Error	Handling method
PDF encrypted	Prompt the user to provide the decryption password
File corrupted	Skip and log the error
Encoding issue	Try automatic encoding detection (UTF-8, GBK, GB2312)
Docling failed	Fall back to PyPDF2
Image recognition failed	Keep the original image and add a "to be supplemented" marker

Script interface

parse_doc.py

uv run .claude/skills/req-parser/scripts/parse_doc.py \
  --input-dir <输入目录> \
  --output-dir <输出目录> \
  [--force]  # 强制覆盖已有文件

Return value：

• 0: Success
• 1: Partial failure (some files could not be parsed)
• 2: Complete failure

Output: Parse statistics JSON

{
  "total": 5,
  "success": 4,
  "failed": 1,
  "failed_files": ["encrypted.pdf"]
}