fix: Improve agent prompt clarity for JSON output

- Use concrete examples instead of "passed|failed|skipped" placeholders
- Add clear instruction to replace example values with actual findings
- Remove debug logging from requirements-reviewer

The placeholder format was causing Claude to output the literal text
instead of choosing one status value.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: sylvansys

.constellos/agents/code-quality.md

@@ -46,61 +46,58 @@ You must evaluate each of these checks independently:
 
 ## Output Format
 
-**CRITICAL**: Output ONLY the JSON block below. Each check MUST have a status.
+**CRITICAL**: After your review, output a single JSON block with your findings.
 
+For each check, set `status` to exactly one of: `"passed"`, `"failed"`, or `"skipped"`.
+- Use `"passed"` if no issues found
+- Use `"failed"` if any issues found
+- Use `"skipped"` if check is not applicable
+
+Example output:
 ```json
 {
   "checks": [
     {
       "name": "DRY",
-      "status": "passed|failed|skipped",
-      "result": "Brief 1-line result",
-      "reasoning": "Why this status was given",
-      "files": [
-        {
-          "path": "path/to/file.ts",
-          "line": 42,
-          "note": "Specific issue or observation"
-        }
-      ]
+      "status": "passed",
+      "result": "No code duplication found",
+      "reasoning": "Each component has unique logic with no repeated patterns",
+      "files": []
     },
     {
       "name": "YAGNI",
-      "status": "passed|failed|skipped",
-      "result": "Brief 1-line result",
-      "reasoning": "Why this status was given",
+      "status": "passed",
+      "result": "No over-engineering detected",
+      "reasoning": "Implementation matches requirements without unnecessary complexity",
       "files": []
     },
     {
       "name": "Modularity",
-      "status": "passed|failed|skipped",
-      "result": "Brief 1-line result",
-      "reasoning": "Why this status was given",
+      "status": "passed",
+      "result": "Good separation of concerns",
+      "reasoning": "Components have single responsibilities and clear interfaces",
       "files": []
     },
     {
       "name": "Maintainability",
-      "status": "passed|failed|skipped",
-      "result": "Brief 1-line result",
-      "reasoning": "Why this status was given",
+      "status": "passed",
+      "result": "Code is readable and well-structured",
+      "reasoning": "Clear naming, appropriate comments, logical organization",
       "files": []
     },
     {
       "name": "Error Handling",
-      "status": "passed|failed|skipped",
-      "result": "Brief 1-line result",
-      "reasoning": "Why this status was given",
+      "status": "skipped",
+      "result": "No error handling code in changes",
+      "reasoning": "Changes are configuration files only",
       "files": []
     }
   ],
-  "message": "Optional overall assessment (leave empty if not needed)"
+  "message": ""
 }
 ```
 
-## Status Guidelines
-- **passed**: No issues found for this check
-- **failed**: One or more issues found - be strict, fail if there are ANY violations
-- **skipped**: Check not applicable (e.g., no error handling code to review)
+**Important**: Replace the example values above with your actual findings. The status must be one of: `passed`, `failed`, or `skipped`.
 
 ## Severity in Files
 When adding files, prioritize high-severity issues:

.constellos/agents/requirements.md

@@ -38,47 +38,43 @@ You must evaluate each of these checks independently:
 
 ## Output Format
 
-**CRITICAL**: Output ONLY the JSON block below. Each check MUST have a status.
+**CRITICAL**: After your review, output a single JSON block with your findings.
+
+For each check, set `status` to exactly one of: `"passed"`, `"failed"`, or `"skipped"`.
+- Use `"passed"` if check criteria are fully satisfied
+- Use `"failed"` if any issues are found
+- Use `"skipped"` if check is not applicable (e.g., no issue context)
 
 ```json
 {
   "checks": [
     {
       "name": "Completeness",
-      "status": "passed|failed|skipped",
-      "result": "Brief 1-line result",
-      "reasoning": "Why this status was given",
-      "files": [
-        {
-          "path": "path/to/file.ts",
-          "line": 42,
-          "note": "Missing requirement X implementation"
-        }
-      ]
+      "status": "passed",
+      "result": "All acceptance criteria implemented",
+      "reasoning": "Each requirement from the issue is addressed in the code changes",
+      "files": []
     },
     {
       "name": "Scope",
-      "status": "passed|failed|skipped",
-      "result": "Brief 1-line result",
-      "reasoning": "Why this status was given",
+      "status": "passed",
+      "result": "Changes within scope",
+      "reasoning": "All changes relate directly to the issue requirements",
       "files": []
     },
     {
       "name": "Traceability",
-      "status": "passed|failed|skipped",
-      "result": "Brief 1-line result",
-      "reasoning": "Why this status was given",
+      "status": "skipped",
+      "result": "No tests required for config change",
+      "reasoning": "This is a workflow configuration change, not a code change requiring tests",
       "files": []
     }
   ],
-  "message": "Optional overall assessment (leave empty if not needed)"
+  "message": ""
 }
 ```
 
-## Status Guidelines
-- **passed**: Check criteria fully satisfied
-- **failed**: One or more issues found - be strict, fail if there are ANY violations
-- **skipped**: Check not applicable (e.g., no issue context available)
+**Important**: Replace the example values above with your actual findings. The status must be one of: `passed`, `failed`, or `skipped`.
 
 ## Guidelines
 - Be strict about scope - extra features should be flagged

.github/actions/requirements-reviewer/action.yml

@@ -52,16 +52,10 @@ runs:
 
         BRANCH="${{ inputs.branch }}"
         echo "branch=$BRANCH" >> $GITHUB_OUTPUT
-        echo "DEBUG: Branch name is '$BRANCH'"
 
         # Extract issue number from branch name (e.g., "123-feature-name")
         ISSUE=""
-        if [[ $BRANCH =~ ^([0-9]+)- ]]; then
-          ISSUE="${BASH_REMATCH[1]}"
-          echo "DEBUG: Extracted issue '$ISSUE' from branch name"
-        else
-          echo "DEBUG: Branch name did not match pattern ^([0-9]+)-"
-        fi
+        [[ $BRANCH =~ ^([0-9]+)- ]] && ISSUE="${BASH_REMATCH[1]}"
 
         # Fallback 1: Parse PR body for "Closes #X", "Fixes #X", "Resolves #X"
         if [ -z "$ISSUE" ]; then
@@ -89,24 +83,15 @@ runs:
           [ "$ISSUE" = "null" ] && ISSUE=""
         fi
 
-        echo "DEBUG: Final issue number is '$ISSUE'"
         echo "issue=$ISSUE" >> $GITHUB_OUTPUT
 
         # Get changed files (gracefully handle permission errors)
         gh pr view ${{ inputs.pr_number }} --json files --jq '.files[].path' > .claude/review-context/changed.txt 2>/dev/null || touch .claude/review-context/changed.txt
 
         # Get issue context if available
         if [ -n "$ISSUE" ]; then
-          echo "DEBUG: Fetching issue $ISSUE..."
-          if gh issue view $ISSUE --json title,body > .claude/review-context/issue.json 2>&1; then
-            echo "DEBUG: Issue fetch succeeded, content:"
-            cat .claude/review-context/issue.json | head -c 200
-          else
-            echo "DEBUG: Issue fetch failed, using empty JSON"
-            echo "{}" > .claude/review-context/issue.json
-          fi
+          gh issue view $ISSUE --json title,body > .claude/review-context/issue.json 2>/dev/null || echo "{}" > .claude/review-context/issue.json
         else
-          echo "DEBUG: No issue number, using empty JSON"
           echo "{}" > .claude/review-context/issue.json
         fi