📝[Enhancement]: Add structured reporting during the process (#197)

## Description

This pull request updates the workflow prompts for the GitHub automation
scripts to improve user communication and reporting. The main change is
that each major phase (specification, clarification, planning, task
generation, and analysis) now posts a clear status comment to the GitHub
issue, summarizing progress and next steps for users. Additionally, the
analysis and clarification steps now produce more structured, readable
markdown reports.

Key improvements include:

**User Communication Enhancements:**

* Each major workflow step (`specify`, `clarify`, `plan`, `tasks`,
`analyze`) now posts a standardized status comment to the issue, clearly
indicating completion and next recommended actions.
[[1]](diffhunk://#diff-fa401fef0198b14e6b962bab378aefea7dac6156cbe91dc0ccf1f4de2a56e0fdL140-R142)
[[2]](diffhunk://#diff-c0d19cb5a033f16f5989ac19b6c95af3bce61c8e84952ffb48009ed901264115L145-R162)
[[3]](diffhunk://#diff-68a2c56959d80cc612e224742a5036c1110c7d7242c7970cea384847a63d2f74L141-R144)
[[4]](diffhunk://#diff-dae60ede84de8dbfbeaa4633505d0c420ce25288ca04d74ac85b28454fad0734L112-R114)
[[5]](diffhunk://#diff-149f5825020c21985a8967be1c77807826b4c395a3153ee54414ad90b862ffbbL97-R136)

**Analysis and Clarification Reporting:**

* The analysis step now posts a detailed markdown comment with tables
grouped by severity, a summary, and explicit next actions, making
findings easier to review and act upon.
* The clarification step now posts a markdown summary table of questions
and answers if any were asked, improving traceability of clarifications.

**Process and Flow Improvements:**

* The planning step now checks for clarifications before proceeding,
pausing if ambiguous areas remain and instructing the user on how to
resolve them.
* Each phase's reporting is reorganized to ensure the status comment is
posted before the detailed completion report, improving user guidance
and flow.
[[1]](diffhunk://#diff-fa401fef0198b14e6b962bab378aefea7dac6156cbe91dc0ccf1f4de2a56e0fdL140-R142)
[[2]](diffhunk://#diff-68a2c56959d80cc612e224742a5036c1110c7d7242c7970cea384847a63d2f74L141-R144)
[[3]](diffhunk://#diff-dae60ede84de8dbfbeaa4633505d0c420ce25288ca04d74ac85b28454fad0734L112-R114)

These changes collectively make the workflow more transparent,
actionable, and user-friendly.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [x] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

.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: `<https://example.com>`)
 - 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:**
 
@@ -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)

.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.

.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'".

.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 | <question text> | <answer text> |
+     | 2 | <question text> | <answer text> |
+     | ... | ... | ... |
+
+     _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).

.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.

.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 <issue-number> --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.

.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 "<your-generated-name>"`](../../.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)
@@ -137,6 +141,8 @@ Given that feature description, do this:
    gh issue edit <issue-number> --body-file <SPEC_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.

.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