corezoid-process-tech-writer

name

corezoid-process-tech-writer

description

Documents a Corezoid process — produces a human-readable Markdown file AND enriches the process JSON with descriptions on every node and parameter. Output is designed for team wikis, internal portals, and future product integration. Activate whenever a user asks to document a process, write docs for a connector, add descriptions to a process, create documentation for a logic, describe what a process does, or any similar phrasing. Also activate when the user shares a process JSON and asks to explain it or make it self-documenting. Always produce BOTH outputs (Markdown file + enriched JSON) — never just one.

Corezoid Process Tech Writer

Always produce two outputs for every process:

1. Markdown documentation file at .processes/<name>-docs.md
2. Enriched process JSON (same file, description fields filled in) at .processes/<name>-enriched.json

---

Step 0 — Load the process

If the user provides a file path, read it directly. If they provide a process name or ID, use pull-process to fetch it first.

---

How to extract information from the process JSON

Inputs

Read the params array. Each entry has:

• name — parameter name
• type — data type
• descr — description (may be empty — infer from context)
• flags — "required" flag means mandatory; "input" = input param, "output" = output param
• regex — validation pattern (document if non-empty)

Outputs

Find all nodes with api_rpc_reply logic in condition.logics:

• throw_exception: false → success response — document res_data keys and types
• throw_exception: true → error response — document what triggers it (node title, exception_reason if present)

Process flow

Walk scheme.nodes following go entries from the Start node (obj_type: 1):

• Start → node with id matching the to_node_id in Start's go logic
• Continue following go entries to map the happy path
• Note branches at Condition nodes or go_if_const entries
• Note error paths via err_node_id references

External dependencies

• API Call nodes (api logic): extract url, method, extra_headers
• {{env_var[@name]}} references: list all unique variable names used
• Code nodes (api_code): look for referenced services or data transformations
• Call Process nodes (api_rpc): extract conv_id values (called process IDs)

---

Output 1: Markdown documentation

Save to .processes/<process-name-in-snake-case>-docs.md.

Use this exact structure:

# <Process Title>

## Overview
<1-2 sentences: what this process does and when to call it. Be specific about the business purpose.>

## Input Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| field_name | string | Yes | Description from params.descr |
| optional_field | number | No | Description |

<If any field has regex validation, add a "Validation" subsection listing the rules.>

## Output

### Success response
| Field | Type | Description |
|-------|------|-------------|
| response | object | The API response body |

### Error cases
| Error | Trigger condition |
|-------|------------------|
| "Code node error" | JavaScript execution failed in the preparation step |
| "API call error" | External API returned an error or was unreachable |

## How to Call

Example `task_data` with realistic values:
​```json
{
  "field_name": "example_value",
  "optional_field": 42
}
​```

## Process Flow

1. **Start** — Entry point, receives the task
2. **<Code Node title>** — <plain English: what this step does>
3. **<API Call / Call Process title>** — <plain English: what is called and why>
4. **<Reply node title>** — <what is returned on success>
5. **Final** — Task stored, process complete

<For error paths, describe them after the happy path:>

**Error path (Code Node failure):** If the preparation step fails, an error reply is returned
with the exception description, and the task ends at the Error node.

## External Dependencies

| Dependency | Type | Variable / URL |
|-----------|------|----------------|
| <service name> | HTTP API | `{{env_var[@variable-name]}}` |
| <process name> | Corezoid process | ID: `<conv_id>` |

## Notes

- <Any timeouts configured via semaphors — e.g. "API call has a 30-second timeout">
- <Rate limiting (max_threads setting)>
- <Any other relevant technical notes>

---

Output 2: Enriched process JSON

Read the original process JSON, add description fields to every node, and write the result to .processes/<name>-enriched.json.

Rules for node enrichment

What to fill:

• description field on every node — one plain English sentence: what this node does in the context of this process
• params[].descr — if empty, infer from the field name and process context

What NOT to change:

• id, obj_type, condition, logics, semaphors — never touch these
• x, y, extra, options — leave as-is
• title — only fill if the field is completely empty ("")

Description style:

• One sentence, active voice, present tense
• Specific to this process — not generic ("Handles errors" is bad; "Returns an error reply if the actor creation API call fails" is good)
• Reference actual data fields and external services where relevant

Examples:

Node type	Bad description	Good description
Code node	"Prepares data"	"Builds the request body with actor_name, form_id, and authorization_header for the Simulator API call"
API Call	"Makes API call"	"Sends POST request to Simulator API to create a new actor with the prepared parameters"
Reply Success	"Returns response"	"Returns the created actor data from the Simulator API back to the calling process"
Reply Error	"Returns error"	"Returns error reply with throw_exception:true when the actor creation API call fails"
Final	"Final"	"Stores the completed task with actor creation result and marks the process as successful"

---

Both files must be produced in the same response

Do not produce one without the other. If the process JSON is very large, produce the Markdown first, then the enriched JSON.