Add visible-reasoning agent; fix reason.prompt.md ↔ agi-reasoning CoT contradiction#188
Merged
Conversation
Agent-Logs-Url: https://github.com/Bryan-Roe/Aria/sessions/af3d17c6-647c-40c5-9828-33c4cc843c72 Co-authored-by: Bryan-Roe <74067792+Bryan-Roe@users.noreply.github.com>
Agent-Logs-Url: https://github.com/Bryan-Roe/Aria/sessions/af3d17c6-647c-40c5-9828-33c4cc843c72 Co-authored-by: Bryan-Roe <74067792+Bryan-Roe@users.noreply.github.com>
Copilot created this pull request from a session on behalf of
Bryan-Roe
April 30, 2026 17:03
View session
Contributor
Reviewer's GuideIntroduces a new visible-reasoning specialist agent that explicitly exposes its step-by-step chain-of-thought to users, retargets the reasoning prompt to this agent, and updates Copilot documentation to clarify and contrast the chain-of-thought behavior between agi-reasoning (internal CoT) and visible-reasoning (visible CoT). Sequence diagram for visible-reasoning agent interaction and handoffsequenceDiagram
actor User
participant Copilot
participant ReasonPrompt
participant VisibleAgent as visible-reasoning
participant PrimaryAgent as agent
User->>Copilot: Request with trigger (show your reasoning)
Copilot->>ReasonPrompt: Select reason.prompt.md
ReasonPrompt-->>Copilot: Metadata (agent_ref = visible-reasoning)
Copilot->>VisibleAgent: Invoke with task and context
VisibleAgent->>VisibleAgent: Analyze
VisibleAgent->>VisibleAgent: Decompose into subtasks
VisibleAgent->>VisibleAgent: Execute subtasks with visible trace
VisibleAgent->>VisibleAgent: Reflect and compute confidence
VisibleAgent-->>User: Reasoning trace + final answer
VisibleAgent->>PrimaryAgent: Handoff(reasoningTrace, decision, assumptions, risks, nextAction)
PrimaryAgent-->>Copilot: Acknowledgement and follow-up actions
Copilot-->>User: Any subsequent results from primary agent
Class diagram for reasoning prompts and agents with CoT exposureclassDiagram
class ReasonPrompt {
+string name
+string description
+string argument_hint
+string agent_ref
+applyFramework(task)
}
class AgiPrompt {
+string name
+string description
+string argument_hint
+string agent_ref
+applyFramework(task)
}
class VisibleReasoningAgent {
+string name
+string description
+string[] tools
+bool chainOfThoughtVisible
+respond(task)
+analyze(task)
+decompose(task)
+executeSubtasks(task)
+reflect()
+computeConfidence()
+handoffToPrimaryAgent(primaryAgent, reasoningTrace, decision, assumptions, risks, nextAction)
}
class AgiReasoningAgent {
+string name
+string description
+string[] tools
+bool chainOfThoughtVisible
+respond(task)
+internalAnalyze(task)
+internalDecompose(task)
+internalExecute(task)
+internalReflect()
+internalConfidence()
}
class PrimaryAgent {
+string name
+string description
+string[] tools
+respond(task)
+continueFromReasoningTrace(reasoningTrace, decision, assumptions, risks, nextAction)
}
ReasonPrompt --> VisibleReasoningAgent : uses
AgiPrompt --> AgiReasoningAgent : uses
VisibleReasoningAgent --> PrimaryAgent : returns_control_to
VisibleReasoningAgent : chainOfThoughtVisible = true
AgiReasoningAgent : chainOfThoughtVisible = false
File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
github-actions
Bot
added
the
documentation
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The Return-to-Agent Contract refers to handing back to
agentas the primary agent, but the agents table listsai.agent.mdas the primary autonomous agent, so it would help to clarify or align the naming to avoid confusion about which agent should receive the handoff. - The visible reasoning template forces a full multi-section trace on every invocation; consider documenting a brief or collapsed mode (e.g., when explicitly requested) so the agent can adapt verbosity to user preference while still honoring the ‘visible reasoning’ semantics.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The Return-to-Agent Contract refers to handing back to `agent` as the primary agent, but the agents table lists `ai.agent.md` as the primary autonomous agent, so it would help to clarify or align the naming to avoid confusion about which agent should receive the handoff.
- The visible reasoning template forces a full multi-section trace on every invocation; consider documenting a brief or collapsed mode (e.g., when explicitly requested) so the agent can adapt verbosity to user preference while still honoring the ‘visible reasoning’ semantics.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Contributor
🔴 Coverage —
|
| Metric | Value |
|---|---|
| Total coverage | 59.6% |
→ vs main |
0.0% |
| Minimum threshold | 60% |
Updated on every push · 2026-04-30
Contributor
There was a problem hiding this comment.
Pull request overview
This PR resolves a documentation/behavior mismatch in the repo’s prompt/agent setup by introducing a new visible-reasoning agent and updating reason.prompt.md to target it, so “show your reasoning” prompts no longer point at an agent intended for hidden/internal reasoning.
Changes:
- Added a new
.github/agents/visible-reasoning.agent.mddescribing a reasoning mode intended to surface step-by-step reasoning output. - Updated
.github/prompts/reason.prompt.mdto useagent: visible-reasoningand adjusted its description accordingly. - Updated
.github/copilot-instructions.mdto document both reasoning agents and clarify which prompts use which agent.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| .github/prompts/reason.prompt.md | Switches the prompt to the new visible-reasoning agent and updates prompt metadata text. |
| .github/copilot-instructions.md | Updates the agents/prompt documentation to distinguish internal vs visible reasoning modes. |
| .github/agents/visible-reasoning.agent.md | Introduces the new agent definition and response format for visible reasoning. |
| @@ -1,8 +1,8 @@ | |||
| --- | |||
| description: "Reason through a problem using chain-of-thought analysis, task decomposition, and self-reflection. Produces structured reasoning with confidence scores and verification steps." | |||
| description: "Reason through a problem with visible chain-of-thought analysis, task decomposition, and self-reflection. Shows reasoning steps to the user, including confidence scores and verification. Use when the user wants to see the reasoning process, not just the final answer." | |||
|
|
||
| ## Workspace Context | ||
|
|
||
| - **Provider chain**: Azure OpenAI → OpenAI → LMStudio → LoRA → Local |
Comment on lines
+29
to
+30
| You are a transparent reasoning agent. Your primary goal is to **show your work**: every analysis step, assumption, confidence score, and self-correction must be visible to the user. This is the opposite of the `agi-reasoning` agent, which hides its chain-of-thought. | ||
|
|
| | `ai.agent.md` | Primary autonomous agent — task decomposition, multi-step execution | | ||
| | `my-agent.agent.md` | QAI specialist — quantum-AI/ML development | | ||
| | `agi-reasoning.agent.md` | Chain-of-thought reasoning, self-reflection | | ||
| | `agi-reasoning.agent.md` | Chain-of-thought reasoning, self-reflection (CoT is internal, final answer only) | |
![bryan-roe-bot[bot]](https://avatars.githubusercontent.com/in/1073263?s=60&v=4){kind=small}
|
|
||
| ## Workspace Context | ||
|
|
||
| - **Provider chain**: Azure OpenAI → OpenAI → LMStudio → LoRA → Local |
Contributor
There was a problem hiding this comment.
Semgrep identified an issue in your code:
Possibly found usage of AI: OpenAI
To resolve this comment:
🔧 No guidance has been designated for this issue. Fix according to your organization's approved methods.
💬 Ignore this finding
Reply with Semgrep commands to ignore this finding.
/fp <comment>for false positive/ar <comment>for acceptable risk/other <comment>for all other reasons
Alternatively, triage in Semgrep AppSec Platform to ignore the finding created by detect-generic-ai-oai.
You can view more details about this finding in the Semgrep AppSec Platform.
Contributor
|
Semgrep found 1 Possibly found usage of AI: OpenAI |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
reason.prompt.mdinstructed "show your reasoning at each step" while pointing atagi-reasoning, whose contract explicitly hides chain-of-thought from users. The two were irreconcilably contradictory, causing repeated issues from reviewers and tooling.Changes
.github/agents/visible-reasoning.agent.md: specialist that surfaces the full reasoning trace (Analyze → Decompose → Execute → Reflect → Confidence → Answer) to the user; includes required Return-to-Agent Contract and a contrast table vsagi-reasoning.github/prompts/reason.prompt.md: switchesagent: agi-reasoning→agent: visible-reasoning; description updated to reflect exposed CoT behavior.github/copilot-instructions.md: agents table and prompts section now document both agents with their distinct CoT exposure semanticsagi-reasoningvisible-reasoningSummary by Sourcery
Introduce a new visible-reasoning agent that exposes chain-of-thought to users and update the reasoning prompt and Copilot documentation to distinguish between hidden and visible reasoning behavior.
New Features:
Enhancements: