{% extends '_base.xml.j2' %}

{% block extra_constraints %}
        <rule priority="high">Do NOT over-document.</rule>
        <rule priority="high">Do NOT document internal implementation details.</rule>
        <rule priority="high">Do NOT create docs for trivial changes.</rule>
        <rule priority="medium">When unsure, skip (avoid scope creep).</rule>
{% endblock %}

{% block instructions %}
        <phase name="prerequisites">
            <check>If current_failures non-empty, set step back to code-review and exit.</check>
        </phase>

        <phase name="get_bearings">
            <commands><![CDATA[
pwd
cat .claudesprint/project/current_issue.json
ISSUE_ID=$(cat .claudesprint/project/current_issue.json | jq -r '.issue_id')
claudesprint-tools sprint details "$ISSUE_ID"
ls -la docs/ 2>/dev/null || echo "No docs directory"
            ]]></commands>
        </phase>

        <phase name="skip_docs_criteria">
            <description>Skip docs update if ALL of these are true:</description>
            <criterion>Category NOT api, feature, ui, or infrastructure</criterion>
            <criterion>No new public APIs added</criterion>
            <criterion>No user-facing behavior changed</criterion>
            <criterion>No configuration options added</criterion>
            <criterion>/docs directory doesn't exist</criterion>
            <action>If skipping:
                - Set step to stage-changes
                - Log: "Skipped docs: &lt;reason&gt;"</action>
        </phase>

        <phase name="require_docs_criteria">
            <description>Require docs update if ANY of these are true:</description>
            <criterion>Category is api with new endpoints</criterion>
            <criterion>Category is feature with new user-facing functionality</criterion>
            <criterion>New config options or env variables added</criterion>
            <criterion>Existing documented behavior changed</criterion>
            <criterion>Acceptance criteria mention "documentation"</criterion>
        </phase>

        <phase name="update_documentation">
            <setup><![CDATA[
mkdir -p docs
            ]]></setup>
            <mapping>
                <change_type destination="docs/api.md">API endpoint</change_type>
                <change_type destination="docs/features/<feature>.md or README.md">Feature</change_type>
                <change_type destination="docs/configuration.md or README.md">Config</change_type>
            </mapping>
            <guidelines>
                <guideline>Clear language</guideline>
                <guideline>Code examples where helpful</guideline>
                <guideline>Follow existing style</guideline>
                <guideline>Focus on WHAT and HOW</guideline>
            </guidelines>
        </phase>

        <phase name="update_current_issue_json">
            <update field="step">stage-changes</update>
            <update field="changes">Add: doc files created/modified</update>
            <important>Preserve existing changes array.</important>
        </phase>

        <phase name="log_and_exit">
            <commands><![CDATA[
echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] STEP: update-docs -> stage-changes" >> .claudesprint/project/current_issue.log
echo "  Docs: <updated/skipped>" >> .claudesprint/project/current_issue.log
echo "  Decision: <Updated docs: summary OR Skipped docs: reason>" >> .claudesprint/project/current_issue.log
            ]]></commands>
        </phase>
{% endblock %}

{% block termination %}
        <note>No termination tag required for this step.</note>
{% endblock %}
