speccrew-knowledge-bizs-ui-analyze

name	speccrew-knowledge-bizs-ui-analyze
description	Analyze a single UI feature from source code to extract business functionality and generate feature documentation using XML Block workflow. Used by Worker Agent in parallel execution during knowledge base initialization Stage 2. Each worker analyzes one feature (e.g., one Vue/React page component).
tools	Read, Write, Edit, Glob, Grep, Bash

UI Feature Analysis - Single Feature (XML Block Workflow)

CRITICAL CONSTRAINT: DO NOT create temporary scripts, batch files, or workaround code files (.py, .bat, .sh, .ps1, etc.) under any circumstances. If execution encounters errors, STOP and report the exact error. Fixes must be applied to the Skill definition or source scripts — not patched at runtime.

Analyze one specific UI feature from source code, extract business functionality, and generate feature documentation. This skill operates at feature granularity - one worker per feature file.

Trigger Scenarios

• "Analyze feature {fileName} from source code"
• "Extract UI functionality from feature {fileName}"
• "Generate documentation for feature {fileName}"
• "Analyze UI feature from features.json"

Input Variables

Variable	Type	Description	Example
{{feature}}	object	Complete feature object from features.json	-
{{fileName}}	string	Feature file name	"index", "UserForm"
{{sourcePath}}	string	Relative path to source file	"frontend-web/src/views/system/user/index.vue"
{{documentPath}}	string	Target path for generated document	"speccrew-workspace/knowledges/bizs/web-vue/src/views/system/user/index.md"
{{module}}	string	Business module name (from feature.module)	"system", "trade", "_root"
{{analyzed}}	boolean	Analysis status flag	true / false
{{platform_type}}	string	Platform type	"web", "mobile"
{{platform_subtype}}	string	Platform subtype	"vue", "react"
{{tech_stack}}	array	Platform tech stack	["vue", "typescript"]
{{language}}	string	REQUIRED - Target language for generated content	"zh", "en"

Language Adaptation

CRITICAL: Generate all content in the language specified by the {{language}} parameter.

• {{language}} == "zh" → Generate all content in 中文
• {{language}} == "en" → Generate all content in English
• Other languages → Use the specified language

All output content (feature names, descriptions, business rules) must be in the target language only.

Output Variables

Variable	Type	Description
{{status}}	string	Analysis status: "success", "partial", or "failed"
{{feature_name}}	string	Name of the analyzed feature
{{generated_file}}	string	Path to the generated documentation file
{{message}}	string	Summary message for status update

Output

Generated Files (MANDATORY - Task is NOT complete until all files are written):

1. {{documentPath}} - Feature documentation file

Return Value (JSON format):

{
  "status": "success|partial|failed",
  "feature": {
    "fileName": "index",
    "sourcePath": "frontend-web/src/views/system/user/index.vue"
  },
  "platformType": "web",
  "module": "system",
  "featureName": "user-management",
  "generatedFile": "speccrew-workspace/knowledges/bizs/web-vue/src/views/system/user/index.md",
  "message": "Successfully analyzed user-management feature from index.vue"
}

Note: Graph data (.graph.json) is handled by speccrew-knowledge-bizs-ui-graph Skill. This Skill generates feature documentation AND writes .done.json completion marker.

AgentFlow Definition

REQUIRED: Before executing this workflow, read the XML workflow specification: speccrew-workspace/docs/rules/agentflow-spec.md

NEVER use create_file to rewrite entire document. Documents MUST be created by copying template then filling with search_replace. NEVER delete generated files. If a file is malformed, fix it with search_replace. NEVER rewrite entire document. Always use targeted search_replace on specific sections. Template copying (Step 5a) MUST execute before section filling (Step 5b). ALL sections in the template must be filled. Use "N/A" for unavailable data, never skip a section. ALL content MUST be generated in the language specified by {{language}} parameter. DO NOT ask user "Should I continue?" or "How would you like to proceed?" during execution DO NOT offer options like "Full execution / Partial / Stop" — always execute ALL tasks to completion DO NOT suggest "Due to context window limits, let me pause" — complete current task, use checkpoint for resumption DO NOT estimate workload and suggest breaking it into phases — execute ALL items in sequence DO NOT warn about "large number of files" or "this may take a while" — proceed with generation Context window management: if approaching limit, save progress to checkpoint file and resume — do NOT ask user for guidance Step 0 Status: SKIPPED (already analyzed) Step 0 Status: PROCEEDING (analysis required)

<!-- Read Template Content -->
<block type="task" id="B1" action="read-file" desc="Read template content">
  <field name="path" value="${templateFile}"/>
  <field name="output" var="templateContent"/>
</block>

<!-- Validate Template Structure -->
<block type="checkpoint" id="CP1" name="template-loaded" desc="Template loaded checkpoint">
  <field name="verify" value="${templateContent} != null AND ${templateContent} != ''"/>
</block>
<block type="event" id="E1" action="log" level="info" desc="Log template read">
  <field name="message">Step 1 Status: COMPLETED - Read template for ${platform_type}/${platform_subtype}</field>
</block>

<!-- Analyze UI Structure -->
<block type="task" id="B2b" action="analyze" desc="Analyze UI structure">
  <field name="content" value="${sourceContent}"/>
  <field name="tech_stack" value="${tech_stack}"/>
  <field name="output" var="analysisResult"/>
  <field name="componentCount" from="${analysisResult.components.length}"/>
  <field name="eventCount" from="${analysisResult.events.length}"/>
  <field name="apiCalls" from="${analysisResult.apis}"/>
  <field name="stateFields" from="${analysisResult.state}"/>
  <field name="formFields" from="${analysisResult.forms}"/>
</block>

<block type="checkpoint" id="CP2" name="source-analyzed" desc="Source analyzed checkpoint">
  <field name="verify" value="${sourceContent} != null"/>
</block>
<block type="event" id="E2" action="log" level="info" desc="Log source analysis">
  <field name="message">Step 2 Status: COMPLETED - Read ${sourcePath}, Analyzed ${componentCount} components, ${eventCount} events</field>
</block>

<!-- Extract Wireframes -->
<block type="task" id="B3b" action="analyze" desc="Extract wireframes">
  <field name="content" value="${sourceContent}"/>
  <field name="platform" value="${platform_type}"/>
  <field name="output" var="wireframes"/>
</block>

<!-- Extract Business Flows -->
<block type="task" id="B3c" action="analyze" desc="Extract business flows">
  <field name="content" value="${sourceContent}"/>
  <field name="events" value="${eventCount}"/>
  <field name="output" var="flows"/>
  <field name="sequenceAnalysis" from="${flows.sequences}"/>
  <field name="boundaryScenarios" from="${flows.boundaries}"/>
</block>

<!-- Extract Data Bindings -->
<block type="task" id="B3d" action="analyze" desc="Extract data bindings">
  <field name="stateFields" value="${stateFields}"/>
  <field name="formFields" value="${formFields}"/>
  <field name="output" var="dataBindingMap"/>
  <field name="reactiveDependencies" from="${dataBindingMap.dependencies}"/>
</block>

<block type="checkpoint" id="CP3" name="features-extracted" desc="Features extracted checkpoint">
  <field name="verify" value="${flows.length} > 0 OR ${wireframes.length} > 0"/>
</block>
<block type="event" id="E3" action="log" level="info" desc="Log feature extraction">
  <field name="message">Step 3 Status: COMPLETED - Extracted ${wireframes.length} wireframes, ${flows.length} business flows</field>
</block>

grep -r "${fileName}" --include="*.{vue,tsx,jsx}" "${sourcePath}/.."

<!-- Search for Component Imports -->
<block type="task" id="B4b" action="run-script" desc="Search import references">
  <field name="command">grep -r "import.*${fileName}" --include="*.{vue,tsx,jsx,ts,js}" "${sourcePath}/.."</field>
  <field name="output" var="importMatches"/>
</block>

<!-- Compile Referencing Pages -->
<block type="task" id="B4c" action="analyze" desc="Compile references">
  <field name="routerMatches" value="${routerMatches}"/>
  <field name="importMatches" value="${importMatches}"/>
  <field name="output" var="referencingPages"/>
</block>

<block type="event" id="E4" action="log" level="info" desc="Log reference search">
  <field name="message">Step 4 Status: COMPLETED - Found ${referencingPages.length} referencing pages</field>
</block>

The output document file MUST be created at the EXACT path specified by ${documentPath} input parameter. DO NOT use the template file name (e.g., FEATURE-DETAIL-TEMPLATE-*.md) as the output file name. The documentPath already contains the correct target path including file name (e.g., speccrew-workspace/knowledges/bizs/web-vue/src/views/system/user/index.md). Before creating the file, ensure the parent directory exists (create if necessary).

<!-- Ensure Document Output Directory Exists -->
<block type="task" id="B5a0" action="run-script" desc="Ensure document output directory exists">
  <field name="command">node -e "require('fs').mkdirSync(require('path').dirname('${documentPath}'), {recursive: true})"</field>
</block>

<!-- Prepare Placeholder Replacements -->
<block type="task" id="B5a1" action="analyze" desc="Prepare replacements">
  <field name="language" value="${language}"/>
  <field name="fileName" value="${fileName}"/>
  <field name="output" var="replacements"/>
</block>

<!-- Replace Top-Level Placeholders and Write Document Skeleton -->
<block type="task" id="B5a2" action="write-file" desc="Write document skeleton">
  <field name="path" value="${documentPath}"/>
  <field name="content" value="${templateContent}"/>
  <field name="note">Replace placeholders {Feature Name}, {documentPath}, {sourcePath}, {Date}, {FeatureFile}.vue with actual values</field>
</block>

<block type="checkpoint" id="CP5a" name="template-copied" desc="Template copied checkpoint">
  <field name="verify" value="file.exists(${documentPath})"/>
</block>
<block type="event" id="E5a" action="log" level="info" desc="Log template copy">
  <field name="message">Step 5a Status: COMPLETED - Template copied to ${documentPath}</field>
</block>

BEFORE filling template sections, you MUST first count identified UI components and dynamically create the corresponding number of sections in the document. Step 1: Copy template skeleton to target path Step 2: For each identified UI component/area, insert a new numbered sub-section (e.g., 2.1, 2.2, 2.3...) into the document Step 3: Fill each sub-section with the specific component details (wireframe, interactions, events) NEVER rely on fixed template sections alone — the number of sections MUST match the number of identified UI components For component ${component.name} (type: ${component.type}): insert a ## 2.X sub-section containing Component Wireframe, Props/Events table, Interaction Flow, and State Management Number of generated 2.X sections == ${analysisResult.components.length} search_replace

<!-- Section 2: Interface Prototype -->
<block type="task" id="B5b2" action="run-skill" desc="Fill Section 2">
  <field name="skill">search_replace</field>
  <field name="file_path" value="${documentPath}"/>
  <field name="search" value="## 2. Interface Prototype.*?(?=## 3.|$)"/>
  <field name="replace" value="## 2. Interface Prototype\n\n${wireframes}\n\n### Interface Element Description\n\n${elementDescriptions}"/>
</block>

<!-- Section 3: Business Flow -->
<block type="task" id="B5b3" action="run-skill" desc="Fill Section 3">
  <field name="skill">search_replace</field>
  <field name="file_path" value="${documentPath}"/>
  <field name="search" value="## 3. Business Flow.*?(?=## 4.|$)"/>
  <field name="replace" value="## 3. Business Flow\n\n${businessFlows}\n\n### API Call Sequence Analysis\n\n${sequenceAnalysis}\n\n### Boundary Scenarios\n\n${boundaryScenarios}"/>
</block>

<!-- Section 4: Data Field Definition -->
<block type="task" id="B5b4" action="run-skill" desc="Fill Section 4">
  <field name="skill">search_replace</field>
  <field name="file_path" value="${documentPath}"/>
  <field name="search" value="## 4. Data Field Definition.*?(?=## 5.|$)"/>
  <field name="replace" value="## 4. Data Field Definition\n\n### Page State Fields\n\n${stateFieldsTable}\n\n### Form Fields\n\n${formFieldsTable}\n\n### Data Binding Mapping\n\n${dataBindingMap}\n\n### Reactive Dependency Chain\n\n${reactiveDependencies}"/>
</block>

<!-- Section 5: References -->
<block type="task" id="B5b5" action="run-skill" desc="Fill Section 5">
  <field name="skill">search_replace</field>
  <field name="file_path" value="${documentPath}"/>
  <field name="search" value="## 5. References.*?(?=## 6.|$)"/>
  <field name="replace" value="## 5. References\n\n### APIs\n\n${apiReferences}\n\n### Shared Methods\n\n${sharedMethods}\n\n### Shared Components\n\n${sharedComponents}\n\n### Other Pages\n\n${otherPages}\n\n### Referenced By\n\n${referencedBy}"/>
</block>

<!-- Section 6: Business Rule Constraints -->
<block type="task" id="B5b6" action="run-skill" desc="Fill Section 6">
  <field name="skill">search_replace</field>
  <field name="file_path" value="${documentPath}"/>
  <field name="search" value="## 6. Business Rule Constraints.*?(?=## 7.|$)"/>
  <field name="replace" value="## 6. Business Rule Constraints\n\n### Permission Rules\n\n${permissionRules}\n\n### Business Logic Rules\n\n${businessRules}\n\n### Validation Rules\n\n${validationRules}"/>
</block>

<!-- Section 7: Notes and Additional Information -->
<block type="task" id="B5b7" action="run-skill" desc="Fill Section 7">
  <field name="skill">search_replace</field>
  <field name="file_path" value="${documentPath}"/>
  <field name="search" value="## 7. Notes and Additional Information.*?(?=$)"/>
  <field name="replace" value="## 7. Notes and Additional Information\n\n${notes}\n\n### Performance and Scalability Analysis\n\n${performanceAnalysis}"/>
</block>

<block type="checkpoint" id="CP5b" name="all-sections-filled" desc="All sections filled checkpoint">
  <field name="verify" value="all.sections.filled"/>
</block>
<block type="event" id="E5b" action="log" level="info" desc="Log section filling">
  <field name="message">Step 5b Status: COMPLETED - All sections filled using search_replace</field>
</block>

Step 6 Status: COMPLETED - Analysis success: Successfully analyzed ${fileName} feature from ${sourcePath} Source file not found: ${sourcePath} Template processing error Validation failed: ${error.message} Workflow execution completed

Constraints

1. DO NOT analyze files outside the specified {{sourcePath}}
2. DO NOT generate separate documents for embedded components
3. All content MUST be in the language specified by {{language}}
4. Use search_replace for section filling, NEVER rewrite entire document
5. Mermaid diagrams MUST follow the rules in mermaid-rule.md
6. All links MUST use relative paths, NEVER file:// protocol

Task Completion Report

When the task is complete, report the following:

Status: success | partial | failed

Summary:

• Feature analyzed: {{feature_name}}
• Document generated: {{documentPath}}
• Platform: {{platform_type}}/{{platform_subtype}}
• Module: {{module}}

Files Generated:

• {{documentPath}} - Feature documentation
• completed_dir/markerName.done.json - Completion marker

Note: Graph data (.graph.json) is handled by speccrew-knowledge-bizs-ui-graph Skill. The .done.json completion marker is written by this Skill in Step 7.

Checklist

• Template file selected based on {{platform_type}}
• Template content read successfully
• Source file read and analyzed
• Business features extracted with wireframes
• Referencing pages found
• Template copied to document path
• All sections filled using search_replace
• All content in target language ({{language}})
• Results reported in JSON format
• Done marker file written to completed_dir