Skip to content

Commit 46f1f32

Browse files
abhraina-awsabhraina-aws
authored
feat: added tangent & introspect docs & provided to introspect (#2775)
1 parent 8038416 commit 46f1f32

File tree

3 files changed

+242
-0
lines changed

3 files changed

+242
-0
lines changed

‎crates/chat-cli/src/cli/chat/tools/introspect.rs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,12 @@ impl Introspect {
6262
documentation.push_str("\n\n--- docs/agent-file-locations.md ---\n");
6363
documentation.push_str(include_str!("../../../../../../docs/agent-file-locations.md"));
6464

65+
documentation.push_str("\n\n--- docs/tangent-mode.md ---\n");
66+
documentation.push_str(include_str!("../../../../../../docs/tangent-mode.md"));
67+
68+
documentation.push_str("\n\n--- docs/introspect-tool.md ---\n");
69+
documentation.push_str(include_str!("../../../../../../docs/introspect-tool.md"));
70+
6571
documentation.push_str("\n\n--- docs/todo-lists.md ---\n");
6672
documentation.push_str(include_str!("../../../../../../docs/todo-lists.md"));
6773

@@ -96,6 +102,11 @@ impl Introspect {
96102
documentation
97103
.push_str("• Experiments: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/experiments.md\n");
98104
documentation.push_str("• Agent File Locations: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-file-locations.md\n");
105+
documentation
106+
.push_str("• Tangent Mode: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/tangent-mode.md\n");
107+
documentation.push_str(
108+
"• Introspect Tool: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/introspect-tool.md\n",
109+
);
99110
documentation
100111
.push_str("• Todo Lists: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/todo-lists.md\n");
101112
documentation

‎docs/introspect-tool.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Introspect Tool
2+
3+
The introspect tool provides Q CLI with self-awareness, automatically answering questions about Q CLI's features, commands, and functionality using official documentation.
4+
5+
## How It Works
6+
7+
The introspect tool activates automatically when you ask Q CLI questions like:
8+
- "How do I save conversations with Q CLI?"
9+
- "What experimental features does Q CLI have?"
10+
- "Can Q CLI read files?"
11+
12+
## What It Provides
13+
14+
- **Command Help**: Real-time help for all slash commands (`/save`, `/load`, etc.)
15+
- **Documentation**: Access to README, built-in tools, experiments, and feature guides
16+
- **Settings**: All configuration options and how to change them
17+
- **GitHub Links**: Direct links to official documentation for verification
18+
19+
## Important Limitations
20+
21+
**Hallucination Risk**: Despite safeguards, the AI may occasionally provide inaccurate information or make assumptions. **Always verify important details** using the GitHub documentation links provided in responses.
22+
23+
## Usage Examples
24+
25+
```
26+
> How do I save conversations with Q CLI?
27+
You can save conversations using `/save` or `/save name`.
28+
Load them later with `/load`.
29+
30+
> What experimental features does Q CLI have?
31+
Q CLI offers Tangent Mode and Thinking Mode.
32+
Use `/experiment` to enable them.
33+
34+
> Can Q CLI read and write files?
35+
Yes, Q CLI has fs_read, fs_write, and execute_bash tools
36+
for file operations.
37+
```
38+
39+
## Auto-Tangent Mode
40+
41+
Enable automatic tangent mode for Q CLI help questions:
42+
43+
```bash
44+
q settings introspect.tangentMode true
45+
```
46+
47+
This keeps help separate from your main conversation.
48+
49+
## Best Practices
50+
51+
1. **Be explicit**: Ask "How does Q CLI handle files?" not "How do you handle files?"
52+
2. **Verify information**: Check the GitHub links provided in responses
53+
3. **Use proper syntax**: Reference commands with `/` (e.g., `/save`)
54+
4. **Enable auto-tangent**: Keep help isolated from main conversations
55+
56+
## Configuration
57+
58+
```bash
59+
# Enable auto-tangent for introspect questions
60+
q settings introspect.tangentMode true
61+
```
62+
63+
## Related Features
64+
65+
- **Tangent Mode**: Isolate help conversations
66+
- **Experiments**: Enable experimental features with `/experiment`

‎docs/tangent-mode.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Tangent Mode
2+
3+
Tangent mode creates conversation checkpoints, allowing you to explore side topics without disrupting your main conversation flow. Enter tangent mode, ask questions or explore ideas, then return to your original conversation exactly where you left off.
4+
5+
## Enabling Tangent Mode
6+
7+
Tangent mode is experimental and must be enabled:
8+
9+
**Via Experiment Command**: Run `/experiment` and select tangent mode from the list.
10+
11+
**Via Settings**: `q settings chat.enableTangentMode true`
12+
13+
## Basic Usage
14+
15+
### Enter Tangent Mode
16+
Use `/tangent` or Ctrl+T:
17+
```
18+
> /tangent
19+
Created a conversation checkpoint (↯). Use ctrl + t or /tangent to restore the conversation later.
20+
```
21+
22+
### In Tangent Mode
23+
You'll see a yellow `↯` symbol in your prompt:
24+
```
25+
↯ > What is the difference between async and sync functions?
26+
```
27+
28+
### Exit Tangent Mode
29+
Use `/tangent` or Ctrl+T again:
30+
```
31+
↯ > /tangent
32+
Restored conversation from checkpoint (↯). - Returned to main conversation.
33+
```
34+
35+
## Usage Examples
36+
37+
### Example 1: Exploring Alternatives
38+
```
39+
> I need to process a large CSV file in Python. What's the best approach?
40+
41+
I recommend using pandas for CSV processing...
42+
43+
> /tangent
44+
Created a conversation checkpoint (↯).
45+
46+
↯ > What about using the csv module instead of pandas?
47+
48+
The csv module is lighter weight...
49+
50+
↯ > /tangent
51+
Restored conversation from checkpoint (↯).
52+
53+
> Thanks! I'll go with pandas. Can you show me error handling?
54+
```
55+
56+
### Example 2: Getting Q CLI Help
57+
```
58+
> Help me write a deployment script
59+
60+
I can help you create a deployment script...
61+
62+
> /tangent
63+
Created a conversation checkpoint (↯).
64+
65+
↯ > What Q CLI commands are available for file operations?
66+
67+
Q CLI provides fs_read, fs_write, execute_bash...
68+
69+
↯ > /tangent
70+
Restored conversation from checkpoint (↯).
71+
72+
> It's a Node.js application for AWS
73+
```
74+
75+
### Example 3: Clarifying Requirements
76+
```
77+
> I need to optimize this SQL query
78+
79+
Could you share the query you'd like to optimize?
80+
81+
> /tangent
82+
Created a conversation checkpoint (↯).
83+
84+
↯ > What information do you need to help optimize a query?
85+
86+
To optimize SQL queries effectively, I need:
87+
1. The current query
88+
2. Table schemas and indexes...
89+
90+
↯ > /tangent
91+
Restored conversation from checkpoint (↯).
92+
93+
> Here's my query: SELECT * FROM orders...
94+
```
95+
96+
## Configuration
97+
98+
### Keyboard Shortcut
99+
```bash
100+
# Change shortcut key (default: t)
101+
q settings chat.tangentModeKey y
102+
```
103+
104+
### Auto-Tangent for Introspect
105+
```bash
106+
# Auto-enter tangent mode for Q CLI help questions
107+
q settings introspect.tangentMode true
108+
```
109+
110+
## Visual Indicators
111+
112+
- **Normal mode**: `> ` (magenta)
113+
- **Tangent mode**: `↯ > ` (yellow ↯ + magenta)
114+
- **With profile**: `[dev] ↯ > ` (cyan + yellow ↯ + magenta)
115+
116+
## Best Practices
117+
118+
### When to Use Tangent Mode
119+
- Asking clarifying questions about the current topic
120+
- Exploring alternative approaches before deciding
121+
- Getting help with Q CLI commands or features
122+
- Testing understanding of concepts
123+
124+
### When NOT to Use
125+
- Completely unrelated topics (start new conversation)
126+
- Long, complex discussions (use regular flow)
127+
- When you want the side discussion in main context
128+
129+
### Tips
130+
1. **Keep tangents focused** - Brief explorations, not extended discussions
131+
2. **Return promptly** - Don't forget you're in tangent mode
132+
3. **Use for clarification** - Perfect for "wait, what does X mean?" questions
133+
4. **Experiment safely** - Test ideas without affecting main conversation
134+
135+
## Limitations
136+
137+
- Tangent conversations are discarded when you exit
138+
- Only one level of tangent supported (no nested tangents)
139+
- Experimental feature that may change or be removed
140+
- Must be explicitly enabled
141+
142+
## Troubleshooting
143+
144+
### Tangent Mode Not Working
145+
```bash
146+
# Enable via experiment (select from list)
147+
/experiment
148+
149+
# Or enable via settings
150+
q settings chat.enableTangentMode true
151+
```
152+
153+
### Keyboard Shortcut Not Working
154+
```bash
155+
# Check/reset shortcut key
156+
q settings chat.tangentModeKey t
157+
```
158+
159+
### Lost in Tangent Mode
160+
Look for the `↯` symbol in your prompt. Use `/tangent` to exit and return to main conversation.
161+
162+
## Related Features
163+
164+
- **Introspect**: Q CLI help (auto-enters tangent if configured)
165+
- **Experiments**: Manage experimental features with `/experiment`

0 commit comments

Comments
 (0)