Prompt file imported from IB-Tool/Partitioning (.claude/commands/write-docs.md). Fill in {{arguments}} before use. Copyright stays with the author.

/write-docs — Write Documentation for an IbToolPartion Module

Write documentation for the module: {{arguments}}

Follow these steps in order. Do not skip any step.

Step 1 — Read the target module

Search for {{arguments}} in these locations (in order):

• {{arguments}}.py (root level)
• Try case/name variations as needed

Read the file completely. Identify:

• All public classes and their purpose
• All public methods: parameters, return values, side effects
• Error handling behavior (what is caught, what is raised, what is logged)
• Any calls to processing.run() or safe_processing_run()
• Constants and their meaning

Step 2 — Consult project rules (mandatory)

Read these files before writing anything:

• ai/core/constraints.md — language rules (English for code/docs, German only for UI strings), docstring format
• ai/core/naming-conventions.md — abbreviations, naming patterns
• ai/core/debug-mode.md — how to document debug behavior

Step 3 — Write Google-style docstrings

Add or update docstrings directly in the module source file for every class and every public method that is missing one or has an incomplete one.

Docstring format

def function_name(param1: type, param2: type) -> return_type:
    """Short one-line summary (imperative, ends with period).

    Longer description if needed. Explain the algorithm or approach
    at a high level. Mention side effects.

    Args:
        param1: Description. Include units if applicable (e.g., meters).
        param2: Description.

    Returns:
        Description of what is returned, including type info if
        not obvious from the annotation.

    Raises:
        ValueError: When param1 is None or empty.
        QgsProcessingException: If the underlying algorithm fails.

    Example:
        >>> result = function_name(layer, 10.0)
        >>> assert result is not None
    """

Rules

• Language: English (never German in docstrings or code)
• First line: short imperative phrase, ends with a period
• Args block: one line per parameter, colon-separated
• Raises block: only for errors that callers need to handle
• Example block: only if usage is non-obvious

Step 4 — Decide whether a Markdown doc is needed

Create a new Markdown file if the module:

• Is a new or recently added module
• Has complex domain logic not yet described in docs/ or ai/domain/
• Contains non-obvious workarounds or known limitations

Extend an existing file if the module's topic is already covered.

Skip Markdown if the module is a simple helper and docstrings suffice.

Where to put the Markdown file

Step 5 — Run pylint

Run pylint on the module where docstrings were changed:

pylint <ModuleName>.py

Fix any warnings introduced by your changes.

Step 6 — Update CHANGELOG.md (if present)

Add a line under the [Unreleased] section:

- Docs: Added/updated documentation for `{{arguments}}`

Step 7 — Output

Report:

1. List of functions/classes where docstrings were added or updated
2. Path of the Markdown file created or extended (or reason why none was needed)
3. Whether CHANGELOG.md was updated
4. Any open questions about behavior that should be clarified with the developer