feat(plan-feature): add documentation task generation

docs/constraints.md

@@ -92,6 +92,8 @@ existing instruction in a SKILL.md or CLAUDE.md file.
 | 1.80 | `plan-feature` MUST fall back to Feature → Task hierarchy when no level-1 type exists, without error or user prompting. | `plan-feature/SKILL.md` — Step 6, graceful degradation |
 | 1.81 | `plan-feature` Epic grouping strategy MUST be configurable via interactive prompt or CLAUDE.md Hierarchy Configuration. | `plan-feature/SKILL.md` — Step 5 |
 | 1.82 | `plan-feature` parent issue linking MUST validate that the parent issue's `hierarchyLevel` is higher than the Feature's `hierarchyLevel` before setting the link. | `plan-feature/SKILL.md` — Step 1.5 |
+| 1.83 | `plan-feature` MUST generate a documentation task when the Feature description's "Documentation Considerations" section indicates doc impact (New Content, Updates, or Release Notes). | `plan-feature/SKILL.md` — Step 5 (Documentation task generation) |
+| 1.84 | `plan-feature` MUST NOT generate a documentation task when the Feature description has no "Documentation Considerations" section or states "No Doc Impact". | `plan-feature/SKILL.md` — Step 5 (Documentation task generation) |
 
 ### Prior Art — Cross-phase integrity (§1.33–1.35)
 
@@ -172,7 +174,7 @@ existing instruction in a SKILL.md or CLAUDE.md file.
 
 Each constraint above references its source. The full source files are:
 
-- `plugins/sdlc-workflow/skills/plan-feature/SKILL.md` — Guardrails (§1.1–1.3), Step 1 Priority/fixVersion extraction (§1.74, §1.76), Step 1.5 Parent linking (§1.82), Step 2.5 Discover Project Issue Types (§1.62–1.64), Step 4.5 Determine Workflow Mode (§1.27), Step 5 Epic grouping (§1.79, §1.81), Step 5 Convention-aware task enrichment (§4.11, §4.13), Step 5 Target Branch assignment (§4.12), Step 5 Bookend task generation (§3.4), Step 6 sub-step 6a.0 Epic creation (§1.79), Step 6 graceful degradation (§1.80), Step 6 Priority/fixVersion inheritance (§1.74, §1.75, §1.76), Step 6a Digest posting (§1.33), Task Description Template (§4.1–4.10)
+- `plugins/sdlc-workflow/skills/plan-feature/SKILL.md` — Guardrails (§1.1–1.3), Step 1 Priority/fixVersion extraction (§1.74, §1.76), Step 1.5 Parent linking (§1.82), Step 2.5 Discover Project Issue Types (§1.62–1.64), Step 4.5 Determine Workflow Mode (§1.27), Step 5 Epic grouping (§1.79, §1.81), Step 5 Convention-aware task enrichment (§4.11, §4.13), Step 5 Target Branch assignment (§4.12), Step 5 Bookend task generation (§3.4), Step 5 Documentation task generation (§1.83, §1.84), Step 6 sub-step 6a.0 Epic creation (§1.79), Step 6 graceful degradation (§1.80), Step 6 Priority/fixVersion inheritance (§1.74, §1.75, §1.76), Step 6a Digest posting (§1.33), Task Description Template (§4.1–4.10)
 - `plugins/sdlc-workflow/skills/implement-task/SKILL.md` — Important Rules (§1.4–1.6, §5.1–5.3), Step 1 (§1.6), Step 1.5 Digest verification (§1.34, §1.35), Step 4/6/9 (§5.4), Step 5 (§1.15, §3.1, §3.4), Step 7 (§5.9–5.13), Step 9 (§2.1–2.3, §5.6–5.8), Step 10 (§3.2, §3.3)
 - `plugins/sdlc-workflow/shared/task-description-template.md` — Rules (§4.12)
 - `plugins/sdlc-workflow/shared/description-digest-protocol.md` — Digest format and verification procedure (§1.33, §1.34, §1.35)

evals/plan-feature/evals.json

@@ -7,7 +7,7 @@
       "expected_output": "A structured implementation plan with task decomposition, each task following task-description-template.md format, with clear dependency ordering. Tasks should reference real file paths from the repo manifest.",
       "files": ["files/feature-standard.md", "files/repo-backend.md"],
       "assertions": [
-        "Each task file contains all required template sections: Repository, Target Branch, Description, at least one of Files to Modify or Files to Create, Implementation Notes, Acceptance Criteria, Test Requirements",
+        "Each non-documentation task file contains all required template sections: Repository, Target Branch, Description, at least one of Files to Modify or Files to Create, Implementation Notes, Acceptance Criteria, Test Requirements. Documentation tasks (tasks whose filename or description indicates doc-only scope) are exempt from requiring Files to Modify, Files to Create, and Implementation Notes — they must still include Repository, Target Branch, Description, Acceptance Criteria, and Test Requirements",
         "Task count is between 3 and 10 inclusive",
         "All tasks reference repository 'trustify-backend'",
         "Task dependencies form a DAG with no circular dependencies",
@@ -16,13 +16,14 @@
         "Every generated task description contains a Repository section with a single repository name (not multiple repos per task)",
         "Every generated task description contains Target Branch, Description, Acceptance Criteria, and Test Requirements sections as required by the handoff contract in task-description-template.md",
         "File paths in Files to Modify and Files to Create reference paths from the repo-backend.md mock repository structure manifest, not invented paths",
-        "Implementation Notes in every task reference specific file paths and code patterns from the repository, not abstract or generic guidance",
+        "Implementation Notes in every non-documentation task reference specific file paths and code patterns from the repository, not abstract or generic guidance. Documentation tasks are exempt from this requirement as they intentionally omit Implementation Notes",
         "Every generated task description contains a Target Branch section set to 'main'",
         "After each task is created, a description digest comment is posted with a format-tagged SHA-256 hash — exactly 64 lowercase hex characters prefixed by 'sha256-md:' or 'sha256-adf:', not a placeholder, abbreviated value, or example string. Marker format: '[sdlc-workflow] Description digest: sha256-md:<64-char-hex>' (or sha256-adf). The digest is computed by re-fetching the description from the API and running scripts/sha256-digest.py",
         "Convention-aware enrichment validates file-type applicability per shared/convention-applicability-rules.md before including a convention — inapplicable conventions are excluded entirely (not listed with 'Not applicable' annotations), and applicable ones include a rationale in the prescribed format ('Applies: task modifies <file> matching the convention's <scope>'), not free-form prose",
         "When the Feature issue has a priority set (not 'Undefined'), every created task's additional_fields includes 'priority' with the inherited priority name. When the Feature's priority is 'Undefined', the priority key is omitted entirely from additional_fields (not set to null or 'Undefined')",
         "When the Feature issue has a non-empty fixVersions array and the fixVersion scope config (from ### Jira Field Defaults in CLAUDE.md) is 'task' or 'both' (or absent, defaulting to 'both'), every created task's additional_fields includes 'fixVersions' with the inherited version(s). When fixVersion scope is 'feature' or the Feature has no fixVersions, the fixVersions key is omitted entirely from additional_fields",
-        "The summary comment on the feature issue (Step 6c) includes the inherited priority and fixVersion values that were propagated to tasks, or states they were omitted and why"
+        "The summary comment on the feature issue (Step 6c) includes the inherited priority and fixVersion values that were propagated to tasks, or states they were omitted and why",
+        "A documentation task is generated because the feature description's Documentation Considerations section indicates doc impact (Updates — add endpoint to REST API reference). The documentation task includes Repository, Target Branch, Description, Acceptance Criteria, Test Requirements, and Dependencies sections, and omits Files to Modify, Files to Create, API Changes, Implementation Notes, Reuse Candidates, and Verification Commands"
       ]
     },
     {
@@ -44,7 +45,8 @@
         "Convention-aware enrichment validates file-type applicability per shared/convention-applicability-rules.md before including a convention — inapplicable conventions are excluded entirely (not listed with 'Not applicable' annotations), and applicable ones include a rationale in the prescribed format ('Applies: task modifies <file> matching the convention's <scope>'), not free-form prose",
         "When the Feature issue has a priority set (not 'Undefined'), every created task's additional_fields includes 'priority' with the inherited priority name. When the Feature's priority is 'Undefined', the priority key is omitted entirely from additional_fields (not set to null or 'Undefined')",
         "When the Feature issue has a non-empty fixVersions array and the fixVersion scope config (from ### Jira Field Defaults in CLAUDE.md) is 'task' or 'both' (or absent, defaulting to 'both'), every created task's additional_fields includes 'fixVersions' with the inherited version(s). When fixVersion scope is 'feature' or the Feature has no fixVersions, the fixVersions key is omitted entirely from additional_fields",
-        "The summary comment on the feature issue (Step 6c) includes the inherited priority and fixVersion values that were propagated to tasks, or states they were omitted and why"
+        "The summary comment on the feature issue (Step 6c) includes the inherited priority and fixVersion values that were propagated to tasks, or states they were omitted and why",
+        "No documentation task is generated because the feature description does not contain a Documentation Considerations section"
       ]
     },
     {
@@ -61,7 +63,7 @@
         "Every generated task description contains a Repository section with a single repository name (not multiple repos per task)",
         "Every generated task description contains Target Branch, Description, Acceptance Criteria, and Test Requirements sections as required by the handoff contract in task-description-template.md",
         "File paths in Files to Modify and Files to Create reference paths from the corresponding mock repository structure manifests (repo-backend.md or repo-frontend.md), not invented paths",
-        "Implementation Notes in every non-bookend task reference specific file paths and code patterns from the repository, not abstract or generic guidance — bookend tasks (create-branch, merge-branch) are exempt as they omit Implementation Notes by design",
+        "Implementation Notes in every non-bookend, non-documentation task reference specific file paths and code patterns from the repository, not abstract or generic guidance — bookend tasks (create-branch, merge-branch) and documentation tasks are exempt as they omit Implementation Notes by design",
         "Every generated task description contains a Target Branch section — either all set to 'main' (direct-to-main workflow) or bookend tasks set to 'main' with intermediate tasks set to the feature issue ID (feature-branch workflow)",
         "After each task is created, a description digest comment is posted with a format-tagged SHA-256 hash — exactly 64 lowercase hex characters prefixed by 'sha256-md:' or 'sha256-adf:', not a placeholder, abbreviated value, or example string. Marker format: '[sdlc-workflow] Description digest: sha256-md:<64-char-hex>' (or sha256-adf). The digest is computed by re-fetching the description from the API and running scripts/sha256-digest.py",
         "Convention-aware enrichment validates file-type applicability per shared/convention-applicability-rules.md before including a convention — inapplicable conventions are excluded entirely (not listed with 'Not applicable' annotations), and applicable ones include a rationale in the prescribed format ('Applies: task modifies <file> matching the convention's <scope>'), not free-form prose",
@@ -101,9 +103,9 @@
         "All intermediate tasks (between the create-branch and merge-branch bookend tasks) have Target Branch set to TC-9005",
         "The create-branch bookend task has Target Branch set to main",
         "The merge-branch bookend task has Target Branch set to main",
-        "All intermediate tasks list the create-branch bookend task as a dependency",
-        "The merge-branch bookend task lists all intermediate tasks as dependencies",
-        "Each task file contains all required template sections: Repository, Target Branch, Description, at least one of Files to Modify or Files to Create, Implementation Notes, Acceptance Criteria, Test Requirements",
+        "All non-documentation intermediate tasks list the create-branch bookend task as a dependency. Documentation tasks may list implementation tasks as dependencies instead of the create-branch bookend task, since documentation depends on implementation completion",
+        "The merge-branch bookend task lists all non-documentation intermediate tasks as dependencies",
+        "Each non-documentation task file contains all required template sections: Repository, Target Branch, Description, at least one of Files to Modify or Files to Create, Implementation Notes, Acceptance Criteria, Test Requirements. Documentation tasks are exempt from requiring Files to Modify, Files to Create, and Implementation Notes — they must still include Repository, Target Branch, Description, Acceptance Criteria, and Test Requirements",
         "The plan includes a workflow:feature-branch label decision to be applied to the feature issue",
         "After each task is created, a description digest comment is posted with a format-tagged SHA-256 hash — exactly 64 lowercase hex characters prefixed by 'sha256-md:' or 'sha256-adf:', not a placeholder, abbreviated value, or example string. Marker format: '[sdlc-workflow] Description digest: sha256-md:<64-char-hex>' (or sha256-adf). The digest is computed by re-fetching the description from the API and running scripts/sha256-digest.py",
         "Convention-aware enrichment validates file-type applicability per shared/convention-applicability-rules.md before including a convention — inapplicable conventions are excluded entirely (not listed with 'Not applicable' annotations), and applicable ones include a rationale in the prescribed format ('Applies: task modifies <file> matching the convention's <scope>'), not free-form prose",

plugins/sdlc-workflow/skills/plan-feature/SKILL.md

@@ -197,6 +197,31 @@ to maintain the full Outcome → Feature → Epic → Task hierarchy.
 5. **If user skips (presses Enter)**: proceed without linking — this step is
    entirely optional.
 
+### Documentation signal extraction
+
+After extracting the standard fields, detect and parse the "Documentation
+Considerations" section from the Feature description. The define-feature skill
+(Step 3i) captures this section with standard categories:
+
+- **New Content** — new documentation pages or sections needed
+- **Updates to existing content** — revisions to existing documentation
+- **Release Notes** — release note entries needed
+- **No Doc Impact** — explicitly no documentation changes required
+
+Extract:
+
+- **Doc impact type**: one of `New Content`, `Updates`, `Release Notes`, or
+  `No Doc Impact`
+- **Details**: any additional context provided (user purpose, reference material,
+  source material)
+
+Store these as documentation signals for use in Step 5 (Documentation task
+generation).
+
+If the Feature description has no "Documentation Considerations" section, record
+that no documentation signals are present — do not prompt the user or treat this
+as an error.
+
 ## Step 2 – Inspect Figma Design
 
 If a Figma URL was provided as an argument, use it directly.
@@ -639,9 +664,44 @@ Annotate each task with its Epic group assignment:
   finalizing.
 - **trivial**: all tasks belong to the single Epic.
 
-### Documentation task guidance
-
-When a feature introduces significant new behavior (new user-facing capabilities, new APIs, or major architectural changes), consider generating a **dedicated documentation-only task** to cover cross-cutting documentation updates that span multiple implementation tasks. Use this when the documentation work is substantial enough to warrant its own task rather than being spread across individual implementation tasks.
+### Documentation task generation
+
+Generate a documentation task when the Feature description contains documentation
+signals extracted in Step 1.
+
+1. **Check for documentation signals**: if no documentation signals were extracted
+   in Step 1 (the Feature description has no "Documentation Considerations" section),
+   skip documentation task generation silently.
+2. **Check doc impact type**: if the doc impact type is "No Doc Impact", skip
+   documentation task generation silently.
+3. **Generate documentation task**: if doc signals are present (New Content, Updates
+   to existing content, or Release Notes), generate a documentation task following
+   the `task-description-template.md` format.
+
+The documentation task description MUST include:
+
+- `## Repository` — the repository where the documentation lives
+- `## Target Branch` — follows the same Target Branch assignment rules as other
+  tasks (see below)
+- `## Description` — what changed (from the Feature overview and requirements),
+  the doc impact type (New Content, Updates, or Release Notes), details from
+  the Documentation Considerations section, and a reference to the Feature issue
+- `## Acceptance Criteria` — verify the documentation accurately reflects the
+  feature's behavior and covers the scope identified in Documentation Considerations
+- `## Test Requirements` — verify the documentation is accurate, complete, and
+  consistent with the implemented feature behavior
+- `## Dependencies` — depends on the implementation tasks (documentation should
+  be written after implementation is complete)
+
+The documentation task MUST omit the following sections (the implementer determines
+which doc files to update based on the description):
+
+- Files to Modify
+- Files to Create
+- API Changes
+- Implementation Notes
+- Reuse Candidates
+- Verification Commands
 
 ### Convention-aware task enrichment