From a1d2168fd424a273eb9754dd7d65b6259e0cb192 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 2 Oct 2025 10:51:30 +0200 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=93=9D[Enhancement]:=20Add=20structur?= =?UTF-8?q?ed=20reporting=20for=20analysis,=20clarification,=20specificati?= =?UTF-8?q?on,=20planning,=20and=20task=20generation=20prompts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/prompts/analyze.prompt.md | 41 ++++++++++++++++++++++++++++++- .github/prompts/clarify.prompt.md | 19 +++++++++++++- .github/prompts/plan.prompt.md | 5 +++- .github/prompts/specify.prompt.md | 4 ++- .github/prompts/tasks.prompt.md | 4 ++- 5 files changed, 68 insertions(+), 5 deletions(-) diff --git a/.github/prompts/analyze.prompt.md b/.github/prompts/analyze.prompt.md index 28add113..a3525777 100644 --- a/.github/prompts/analyze.prompt.md +++ b/.github/prompts/analyze.prompt.md @@ -94,7 +94,46 @@ Execution steps: * Duplication Count * Critical Issues Count -7. At end of report, output a concise Next Actions block: +7. **Post issue comment** with analysis results organized by severity: + - Post a comment to the GitHub issue with the analysis findings + - Format the comment with separate tables for each severity level (only include levels that have findings): + ```markdown + ## Analysis Report + + ### Summary + - Total Requirements: X + - Total Tasks: Y + - Coverage: Z% + - Issues Found: N (A critical, B high, C medium, D low) + + ### Critical Issues + | ID | Category | Location(s) | Summary | Recommendation | + |----|----------|-------------|---------|----------------| + | C1 | ... | ... | ... | ... | + + ### High Priority Issues + | ID | Category | Location(s) | Summary | Recommendation | + |----|----------|-------------|---------|----------------| + | H1 | ... | ... | ... | ... | + + ### Medium Priority Issues + | ID | Category | Location(s) | Summary | Recommendation | + |----|----------|-------------|---------|----------------| + | M1 | ... | ... | ... | ... | + + ### Low Priority Issues + | ID | Category | Location(s) | Summary | Recommendation | + |----|----------|-------------|---------|----------------| + | L1 | ... | ... | ... | ... | + + ### Next Actions + - [Recommendation based on findings] + ``` + - Keep tables concise, limit to 20 findings per severity level + - If more than 20 findings in a category, add a note: "_(Additional N issues not shown - see full report)_" + - Include the complete "Next Actions" block with specific recommendations + +8. At end of report, output a concise Next Actions block: - If CRITICAL issues exist: Recommend resolving them before `/implement`. - If only LOW/MEDIUM issues: User may proceed, but provide improvement suggestions. - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", or "Manually edit tasks.md to add coverage for 'performance-metrics'". diff --git a/.github/prompts/clarify.prompt.md b/.github/prompts/clarify.prompt.md index 4b57b4d7..ed8a26d0 100644 --- a/.github/prompts/clarify.prompt.md +++ b/.github/prompts/clarify.prompt.md @@ -142,7 +142,24 @@ Execution steps: 7. Write the updated spec back to `FEATURE_SPEC`. -8. Report completion (after questioning loop ends or early termination): +8. **Post issue comment** with clarification summary (only if questions were asked and answered): + - Post a comment to the GitHub issue summarizing the clarifications + - Format the comment as: + ```markdown + ## Clarification Session (YYYY-MM-DD) + + | # | Question | Answer | + |---|----------|--------| + | 1 | | | + | 2 | | | + | ... | ... | ... | + + _All clarifications have been integrated into the specification._ + ``` + - Keep the table concise and readable + - Include all questions asked and answers received during this session (up to 5) + +9. Report completion (after questioning loop ends or early termination): - Number of questions asked & answered. - Path to updated spec. - Sections touched (list names). diff --git a/.github/prompts/plan.prompt.md b/.github/prompts/plan.prompt.md index a54e6145..20f7601c 100644 --- a/.github/prompts/plan.prompt.md +++ b/.github/prompts/plan.prompt.md @@ -23,6 +23,7 @@ Given the implementation details provided as an argument, do this: - **If exists**: You are ITERATING on an existing plan. User input should guide refinements/additions to the existing plan content. - **If not exists**: You are CREATING a new plan from scratch. - BEFORE proceeding, inspect FEATURE_SPEC for a `## Clarifications` section with at least one `Session` subheading. If missing or clearly ambiguous areas remain (vague adjectives, unresolved critical choices), PAUSE and instruct the user to run `/clarify` first to reduce rework. Only continue if: (a) Clarifications exist OR (b) an explicit user override is provided (e.g., "proceed without clarification"). Do not attempt to fabricate clarifications yourself. + 2. Read and analyze the feature specification to understand: - The feature requirements and user stories - Functional and non-functional requirements @@ -138,6 +139,8 @@ Given the implementation details provided as an argument, do this: gh issue edit --remove-label "Specification" --add-label "Plan" ``` -9. Report results with branch name, PR URL, file paths, and generated artifacts. +9. **Post final status comment**: "✅ Planning complete. Ready for task generation with `/tasks` or analysis with `/analyze`." + +10. Report results with branch name, PR URL, file paths, and generated artifacts. Use absolute paths with the repository root for all file operations to avoid path issues. diff --git a/.github/prompts/specify.prompt.md b/.github/prompts/specify.prompt.md index 8ee7c199..842b4296 100644 --- a/.github/prompts/specify.prompt.md +++ b/.github/prompts/specify.prompt.md @@ -137,6 +137,8 @@ Given that feature description, do this: gh issue edit --body-file ``` -8. Report completion with branch name, spec file path, whether it's a new or updated feature, issue number, target repository (if fork), and readiness for the next phase. +8. **Post final status comment**: "✅ Specification complete. Ready for clarification with `/clarify` or planning with `/plan`." + +9. Report completion with branch name, spec file path, whether it's a new or updated feature, issue number, target repository (if fork), and readiness for the next phase. Note: The script handles branch creation/reuse and initializes the spec file before writing. diff --git a/.github/prompts/tasks.prompt.md b/.github/prompts/tasks.prompt.md index 513a4938..b1a9e22c 100644 --- a/.github/prompts/tasks.prompt.md +++ b/.github/prompts/tasks.prompt.md @@ -109,7 +109,9 @@ $ARGUMENTS rm temp_body.md ``` -9. Report completion with task count, file path, and PR update status. +9. **Post final status comment**: "✅ Task list ready. Run `/analyze` for quality check or `/implement` to begin execution." + +10. Report completion with task count, file path, and PR update status. Context for task generation: $ARGUMENTS From c2c90a331f58c5eaa233d2492fa44ad5b619d514 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 2 Oct 2025 11:11:53 +0200 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=9D[Docs]:=20Correct=20Markdown=20?= =?UTF-8?q?casing=20and=20improve=20clarity=20in=20documentation=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/instructions/md.instructions.md | 4 ++-- .github/instructions/pwsh.instructions.md | 2 +- .github/prompts/constitution.prompt.md | 12 ++++++------ .github/prompts/specify.prompt.md | 18 +++++++++++------- 4 files changed, 20 insertions(+), 16 deletions(-) diff --git a/.github/instructions/md.instructions.md b/.github/instructions/md.instructions.md index 07a4951c..4834944e 100644 --- a/.github/instructions/md.instructions.md +++ b/.github/instructions/md.instructions.md @@ -5,7 +5,7 @@ description: Markdown style guidelines for consistency across documentation. # Markdown Style Guidelines -This document defines the markdown style guidelines for all markdown files in this repository. These rules follow common markdown linter best practices and ensure consistency across documentation. +This document defines the Markdown style guidelines for all Markdown files in this repository. These rules follow common markdown linter best practices and ensure consistency across documentation. ## Headings @@ -110,7 +110,7 @@ No blank lines before/after code blocks. - Always provide link text in square brackets: `[text](url)` - Do not use bare URLs (wrap them: ``) - For internal repository links, use relative paths starting with `./` or `../` -- Use `.md` extension for links to markdown files +- Use `.md` extension for links to Markdown files **Good:** diff --git a/.github/instructions/pwsh.instructions.md b/.github/instructions/pwsh.instructions.md index cc91256f..fc1f4639 100644 --- a/.github/instructions/pwsh.instructions.md +++ b/.github/instructions/pwsh.instructions.md @@ -629,7 +629,7 @@ Get-ChildItem -Path 'C:\Temp' -Filter '*.txt' -Recurse $true -ErrorAction 'Stop' - Use PowerShell comparison operators (`-eq`, `-ne`, `-gt`, `-lt`, `-ge`, `-le`) - Don't use C-style operators (`==`, `!=`, `>`, `<`) -- Use `-like` for wildcard matching, `-match` for regex +- Use `-like` for wildcard matching, `-match` for regular expression - Use `-contains` for collection membership, not `-eq` - Add `-i` prefix for case-insensitive (default) or `-c` for case-sensitive - Caution with $null comparisons. Comparison order is important depending if the variable is a single item or a collection. diff --git a/.github/prompts/constitution.prompt.md b/.github/prompts/constitution.prompt.md index de00895d..4a78dfe6 100644 --- a/.github/prompts/constitution.prompt.md +++ b/.github/prompts/constitution.prompt.md @@ -64,12 +64,12 @@ Follow this execution flow: 3. Draft / Merge updated constitution content: - In Iteration Mode, integrate new principles/sections with minimal disruption: - * Retain stable identifiers (e.g., keep existing principle numbering unless renumbering is explicitly required or gaps introduced by removals). - * When replacing, either (a) fully substitute content if user confirmed or (b) append revised content and mark old with `DEPRECATED:` prefix plus TODO for removal in a future major version. - - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left). - - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance. - - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious. - - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations. + * Retain stable identifiers (e.g., keep existing principle numbering unless renumbering is explicitly required or gaps introduced by removals). + * When replacing, either (a) fully substitute content if user confirmed or (b) append revised content and mark old with `DEPRECATED:` prefix plus TODO for removal in a future major version. + - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left). + - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance. + - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious. + - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations. 4. Consistency propagation checklist (convert prior checklist into active validations): - Read [`.specify/templates/plan-template.md`](../../.specify/templates/plan-template.md) and ensure any "Constitution Check" or rules align with updated principles. diff --git a/.github/prompts/specify.prompt.md b/.github/prompts/specify.prompt.md index 842b4296..016579d2 100644 --- a/.github/prompts/specify.prompt.md +++ b/.github/prompts/specify.prompt.md @@ -30,7 +30,8 @@ Given that feature description, do this: If detected, extract the upstream repository information (owner/repo). **If fork contribution is detected but information is incomplete**, prompt the user: - ``` + + ```text Fork contribution detected. Please provide the following information: - Upstream organization/owner name (e.g., "microsoft", "PSModule") - Upstream repository name (e.g., "vscode", "PSModule") @@ -51,12 +52,15 @@ Given that feature description, do this: - Examples: "user-authentication", "merge-workflows", "api-rate-limiting", "fix-memory-leak" 3. Run the script [`.specify/scripts/powershell/create-new-feature.ps1 -Json -FeatureDescription "$ARGUMENTS" -BranchName ""`](../../.specify/scripts/powershell/create-new-feature.ps1) from repo root and parse its JSON output for BRANCH_NAME, SPEC_FILE, and IS_EXISTING_BRANCH. All file paths must be absolute. - **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for. - **NOTE** - - The script will prepend an auto-incremented feature number (e.g., `003-`) to your branch name. - - If you're currently on `main` branch, a new feature branch will be created. - - If you're already on a feature branch (starts with 3 digits like `001-`, `002-`, etc.), you'll stay on that branch to iterate on the existing feature. - - This allows you to refine specifications without creating multiple branches for the same feature. + +**IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for. + +**NOTE** + +- The script will prepend an auto-incremented feature number (e.g., `003-`) to your branch name. +- If you're currently on `main` branch, a new feature branch will be created. +- If you're already on a feature branch (starts with 3 digits like `001-`, `002-`, etc.), you'll stay on that branch to iterate on the existing feature. +- This allows you to refine specifications without creating multiple branches for the same feature. 4. **Store fork information (if detected in step 1)**: - If the user indicated this is a fork contribution, create a `.fork-info.json` file in the feature directory (same location as SPEC_FILE) From ac6c32442eaf298b7f0e83d9612a0a75f5bbe5c6 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 2 Oct 2025 11:18:20 +0200 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=93=9D[Docs]:=20Update=20Markdown=20g?= =?UTF-8?q?uidelines=20for=20consistency=20and=20clarity?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/instructions/md.instructions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/instructions/md.instructions.md b/.github/instructions/md.instructions.md index 4834944e..1d37c367 100644 --- a/.github/instructions/md.instructions.md +++ b/.github/instructions/md.instructions.md @@ -252,13 +252,13 @@ See the [logo][logo-img] above. ### HTML -- Avoid HTML in markdown when possible -- Use HTML only for features not supported by markdown +- Avoid HTML in Markdown when possible +- Use HTML only for features not supported by Markdown - Close all HTML tags properly -### File Names +### Filenames -- Use lowercase for markdown file names +- Use lowercase for Markdown filenames - Use hyphens (`-`) not underscores (`_`) to separate words - Use `.md` extension (not `.markdown`) @@ -269,7 +269,7 @@ See the [logo][logo-img] above. ## Linting -To validate markdown files against these guidelines, use a markdown linter such as: +To validate Markdown files against these guidelines, use a Markdown linter such as: - [markdownlint](https://github.com/DavidAnson/markdownlint) - [remark-lint](https://github.com/remarkjs/remark-lint) From ef119bfb3daa49658fc42f7acbbda2ebb897b500 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 2 Oct 2025 11:24:14 +0200 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=93=9D[Docs]:=20Correct=20Markdown=20?= =?UTF-8?q?casing=20for=20consistency=20in=20style=20guidelines?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/instructions/md.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/md.instructions.md b/.github/instructions/md.instructions.md index 1d37c367..2608f82f 100644 --- a/.github/instructions/md.instructions.md +++ b/.github/instructions/md.instructions.md @@ -5,7 +5,7 @@ description: Markdown style guidelines for consistency across documentation. # Markdown Style Guidelines -This document defines the Markdown style guidelines for all Markdown files in this repository. These rules follow common markdown linter best practices and ensure consistency across documentation. +This document defines the Markdown style guidelines for all Markdown files in this repository. These rules follow common Markdown linter best practices and ensure consistency across documentation. ## Headings