From d68d3d8ba2f6115df5b0708018542b565d301120 Mon Sep 17 00:00:00 2001 From: mrizzi Date: Mon, 22 Jun 2026 17:40:29 +0200 Subject: [PATCH 1/4] feat(plan-feature): add documentation task generation from Feature description signals MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add deterministic documentation task generation to plan-feature when the Feature description contains a "Documentation Considerations" section with doc impact signals (New Content, Updates, Release Notes). Replaces the previous advisory-only "Documentation task guidance" paragraph with a formal step that parses signals in Step 1 and generates tasks in Step 5. - Step 1: add "Documentation signal extraction" sub-step - Step 5: replace guidance paragraph with "Documentation task generation" subsection following the Bookend task generation pattern - Add constraints §1.59 and §1.60 to docs/constraints.md - Update Traceability Index with new constraint references - Add eval assertions: positive case (eval 1) and negative case (eval 2) Implements TC-4877 Assisted-by: Claude Code --- docs/constraints.md | 4 +- evals/plan-feature/evals.json | 6 +- .../skills/plan-feature/SKILL.md | 66 ++++++++++++++++++- 3 files changed, 70 insertions(+), 6 deletions(-) diff --git a/docs/constraints.md b/docs/constraints.md index f8fe5fbdf..ad2b691c2 100644 --- a/docs/constraints.md +++ b/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) diff --git a/evals/plan-feature/evals.json b/evals/plan-feature/evals.json index f17fed816..8c21dd4c2 100644 --- a/evals/plan-feature/evals.json +++ b/evals/plan-feature/evals.json @@ -22,7 +22,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 matching the convention's '), 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 matching the convention's '), 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" ] }, { diff --git a/plugins/sdlc-workflow/skills/plan-feature/SKILL.md b/plugins/sdlc-workflow/skills/plan-feature/SKILL.md index 0bf4a5fb0..b5cdb0d5b 100644 --- a/plugins/sdlc-workflow/skills/plan-feature/SKILL.md +++ b/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 From 91dd25e834f3f16fa01e7f04d11720e4822a076e Mon Sep 17 00:00:00 2001 From: mrizzi Date: Mon, 22 Jun 2026 18:33:27 +0200 Subject: [PATCH 2/4] fix(plan-feature): exempt documentation tasks from universal template assertions Update eval case 1 assertions to exempt documentation tasks from requiring Files to Modify, Files to Create, and Implementation Notes sections, since documentation tasks intentionally omit these per the documentation task generation design. Implements TC-4885 Assisted-by: Claude Code --- evals/plan-feature/evals.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/evals/plan-feature/evals.json b/evals/plan-feature/evals.json index 8c21dd4c2..afc90eb53 100644 --- a/evals/plan-feature/evals.json +++ b/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,7 +16,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 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 matching the convention's '), not free-form prose", From 065a2e9f4d2b06f3e1241918a4ca3fb31565a130 Mon Sep 17 00:00:00 2001 From: mrizzi Date: Mon, 22 Jun 2026 18:36:51 +0200 Subject: [PATCH 3/4] fix(plan-feature): exempt documentation tasks from eval-3 Implementation Notes assertion Update eval case 3 assertion to exempt documentation tasks alongside bookend tasks from the Implementation Notes requirement, since documentation tasks intentionally omit this section by design. Implements TC-4886 Assisted-by: Claude Code --- evals/plan-feature/evals.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/evals/plan-feature/evals.json b/evals/plan-feature/evals.json index afc90eb53..5f5aba9bb 100644 --- a/evals/plan-feature/evals.json +++ b/evals/plan-feature/evals.json @@ -63,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 matching the convention's '), not free-form prose", From a6de0e4bae208ff74a50cff39bba261c8e53c351 Mon Sep 17 00:00:00 2001 From: mrizzi Date: Mon, 22 Jun 2026 18:39:02 +0200 Subject: [PATCH 4/4] fix(plan-feature): exempt documentation tasks from eval-5 template and dependency assertions Update eval case 5 assertions to exempt documentation tasks from universal template section requirements and create-branch dependency listing, since documentation tasks have different section and dependency structures by design. Implements TC-4887 Assisted-by: Claude Code --- evals/plan-feature/evals.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/evals/plan-feature/evals.json b/evals/plan-feature/evals.json index 5f5aba9bb..9083c3c98 100644 --- a/evals/plan-feature/evals.json +++ b/evals/plan-feature/evals.json @@ -103,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 matching the convention's '), not free-form prose",