Dify Docs Feature Research

Dify Feature Research

Pre-writing research that combines codebase analysis with community feedback to ensure documentation is grounded in both technical reality and actual user needs.

Before Starting

1. Ask the user which feature, node, or area to research. 2. Confirm which branch to investigate (default: main for both repos). 3. Check if the user has a specific doc page in mind for the rewrite.

Codebase location: Dify's backend logic is split across two repos.

If either is missing as a working directory, ask the user for the path.

Pull latest code before investigating. Run in each repo directory:

git fetch origin && git checkout main && git pull origin main

If the user specified a different branch for either repo, substitute accordingly.

Version pinning matters. dify pins graphon to a specific version. Before reading graphon code, check the pinned version and verify against that tag, not graphon main:

grep '"graphon' ~/Documents/Work/Dify\ Repo/dify/api/pyproject.toml
# e.g. "graphon~=0.2.2" → check out v0.2.2 in graphon, not main

If you read graphon main and document behavior that ships only in an unreleased graphon version, the docs will not match what users see. When in doubt, ask the user whether to verify against the pinned version or graphon main (the latter is appropriate when documenting something the user knows is about to ship).

Research Process

Run Phase 1 and Phase 2 in parallel using subagents where possible.

Phase 1: Codebase Investigation

First decide which repo owns the backend implementation:

Then locate and read the source code, covering all three layers:

Backend implementation — Find the core logic in the repo identified above. Read:

• The main node class (execution logic, _run() method)
• Entity definitions (data models, enums, supported types)
• Any template or streaming logic

Frontend UI — Find the React components in the dify repo (the web frontend was not split out). For workflow nodes, check web/app/components/workflow/nodes/<node_name>/. Read:

• Panel component (what configuration options users see)
• Type definitions (data shape)
• Default values and validation rules

API surface — Trace how the feature's output reaches the API response. Check controllers, response converters, and serialization (all in dify).

Produce a summary of:

• What the feature does (based on code, not existing docs)
• What configuration options exist
• What data types / values are supported
• How results are returned to the user (UI, API, streaming)
• Any notable edge cases or limitations visible in the code

Flag any behavior inferred from code rather than observed in the running product.

Phase 2: Community Feedback

Search for user-reported problems and questions across these channels:

GitHub Issues — Run multiple searches with varied terms. Always search dify; also search graphon when the feature is a built-in workflow node, the graph engine, runtime, or model_runtime:

gh issue list --repo langgenius/dify --search "<feature name>" --limit 30
gh issue list --repo langgenius/dify --search "<alternative name>" --limit 30
gh search issues "<feature> <context>" --repo langgenius/dify --limit 20

# For built-in nodes, engine, runtime, or model_runtime, also:
gh issue list --repo langgenius/graphon --search "<feature name>" --limit 30
gh search issues "<feature> <context>" --repo langgenius/graphon --limit 20

End users typically file in dify even for graphon-owned behavior; graphon's tracker tends to hold engineering-side reports. Check both to avoid missing pain points.

GitHub Discussions — Search for related discussion topics:

gh api "repos/langgenius/dify/discussions?per_page=30" --jq '.[] | select(.title | test("<pattern>"; "i"))'

For each relevant issue or discussion, read the body and top comments to understand:

• What the user was trying to do
• What went wrong or was confusing
• Whether it's a bug, missing feature, or documentation gap

Categorize findings into:

Phase 3: Synthesize

Combine both phases into a structured research summary:

## Feature: [Name]

### How It Works (from code)
- [Key behaviors, configuration options, supported types]
- [API response structure]
- [Edge cases or limitations]
- [Unverified inferences — flagged for user testing]

### Current Documentation
- [What the existing page covers]
- [What it's missing]

### Community Pain Points
| Theme | Issues | Type | Doc impact |
|-------|--------|------|------------|
| ...   | #123   | gap  | Should document |

### Recommended Documentation Scope
- [What to add based on gaps]
- [What to clarify based on confusion]
- [What to explicitly omit and why (bugs, unreleased features)]

Present the summary to the user. Jointly decide what to include before starting the writing phase.

Important

• This skill produces research only. Do not start writing documentation until the user reviews the findings and confirms the scope.
• Flag code-inferred behavior as unverified. Ask the user to test before documenting as fact.
• Distinguish bugs from documentation gaps. Documenting buggy behavior as intended causes more harm than leaving a gap.
• Note issue numbers for traceability. The user may want to reference them when prioritizing what to cover.