Main conversation: Implementing user authentication

Project 25: “The Tangent Explorer” — Context Management

Attribute	Value
File	`KIRO_CLI_LEARNING_PROJECTS.md`
Main Programming Language	N/A (Interaction)
Coolness Level	Level 2: Practical
Difficulty	Level 1: Beginner
Knowledge Area	Context Management

What you’ll build: Simulate a debugging session, switch to a tangent, then return without polluting context.

Why it teaches Context Hygiene: Tangents keep the main thread clean.

Success criteria:

The main context summary ignores tangent content.

Real World Outcome

You’ll learn to use Kiro’s tangent mode to isolate exploratory work, debugging, and side investigations without polluting your main conversation context. This keeps your primary task focused while allowing deep dives into related issues.

Example Workflow:

# Main conversation: Implementing user authentication
$ kiro "implement JWT-based user authentication for the API"

[Kiro starts implementing auth...]

# You notice a dependency version conflict (tangent opportunity)
$ kiro "I'm seeing a dependency conflict with jsonwebtoken. Let me investigate in a tangent."

# Kiro creates a tangent session
[TANGENT MODE: dependency-investigation]

$ kiro "show me all versions of jsonwebtoken in package-lock.json and explain the conflict"
[Kiro analyzes dependencies in tangent]

$ kiro "what's the difference between jsonwebtoken 8.x and 9.x?"
[Kiro researches in tangent]

$ kiro "update to jsonwebtoken 9.5.2 and verify tests pass"
[Kiro fixes the issue in tangent]

# Exit tangent and return to main task
$ kiro "tangent resolved, return to main"

[MAIN CONTEXT: implementing JWT-based user authentication]
[Tangent summary: Fixed jsonwebtoken version conflict -> upgraded to 9.5.2]

# Main context continues, enriched but not polluted
$ kiro "continue implementing auth with the updated jsonwebtoken library"

What you’ll see in the session history:

Main Context (auth-implementation):
├─ User: implement JWT-based auth
├─ Kiro: [implementation steps]
├─ [TANGENT: dependency-investigation]
│  └─ Summary: Upgraded jsonwebtoken 8.x → 9.5.2, tests passing
└─ Kiro: [continues with auth using new library]

Tangent Context (dependency-investigation - ISOLATED):
├─ User: show me all versions of jsonwebtoken
├─ Kiro: [detailed analysis of package-lock.json]
├─ User: what's the difference between 8.x and 9.x?
├─ Kiro: [research on breaking changes]
├─ User: update to 9.5.2 and verify tests
└─ Kiro: [upgrade + test verification]

Key benefit: The main context remains focused on “implement auth” and doesn’t include 15 messages about npm dependency resolution. Only the summary (“upgraded jsonwebtoken → 9.5.2”) is surfaced.

The Core Question You’re Answering

“How do you keep your primary conversation focused while exploring tangential issues, debugging edge cases, or researching related topics without losing all your context to noise?”

Before you use tangent mode, understand this: LLM context windows are finite (even at 200K tokens). Every message consumes context budget. If you debug a webpack config issue (20 messages) in the middle of implementing a feature (30 messages), the combined 50-message thread becomes hard to summarize and maintain focus on the original goal.

Tangent mode isolates exploratory work, keeping the main thread clean and summarizable.

Concepts You Must Understand First

Stop and research these before using tangents:

Context Window and Token Budgets
- What is the context window size for Claude (200K tokens)?
- How many tokens does a typical message consume (prompt + response)?
- What happens when context fills up (automatic summarization vs. truncation)?
- Book Reference: “Designing Data-Intensive Applications” by Martin Kleppmann - Ch. 1 (Data Models)
Conversation Threading and Branching
- How do chat systems maintain conversation history (linear vs. tree structure)?
- What is the difference between forking a conversation and creating a tangent?
- How do you merge insights from a tangent back into the main thread?
- Book Reference: “The Pragmatic Programmer” by Hunt & Thomas - Ch. 7 (Debugging)
Summarization and Information Compression
- How do LLMs summarize long conversations (extractive vs. abstractive summarization)?
- What information is preserved vs. discarded in a summary?
- How do you ensure critical decisions from tangents are surfaced in summaries?
- Book Reference: “Speech and Language Processing” by Jurafsky - Ch. 23 (Summarization)
Context Hygiene Best Practices
- When should you start a tangent vs. continue in the main thread?
- How do you name tangents descriptively (for future reference)?
- What is the “two-level rule” (main + tangent, avoid nested tangents)?
- Book Reference: “Working Effectively with Legacy Code” by Feathers - Ch. 6 (Code Smells)
Cognitive Load Management
- What is working memory capacity (7 ± 2 items) and how does it apply to chat?
- How does context switching (main → tangent → main) affect productivity?
- What is the “one primary task” principle (single focus for the main thread)?
- Book Reference: “Thinking, Fast and Slow” by Daniel Kahneman - Ch. 8 (Cognitive Effort)

Questions to Guide Your Design

Before starting a tangent, ask yourself:

Tangent Trigger Criteria
- Is this issue critical to the main task, or can it be deferred?
- Will exploring this now derail the main conversation for > 5 messages?
- Is this a debugging session that might involve trial-and-error (many iterations)?
- Would solving this in-line make the main thread hard to read later?
Tangent Scope
- What specific question am I trying to answer in the tangent?
- What does “done” look like (clear exit criteria)?
- How will I bring the result back to the main thread (summary format)?
- What happens if the tangent doesn’t resolve the issue (abandon or continue)?
Context Preservation
- What information from the main thread does the tangent need (dependencies)?
- Should the tangent have full access to the codebase, or limited scope?
- How do I avoid repeating context setup in the tangent (cached state)?
- What happens if I start another tangent while in a tangent (nesting limits)?
Return Strategy
- How do I signal “return to main” (explicit command or automatic)?
- What summary information should be surfaced (key decisions, outcomes)?
- Do I need to re-state the main task when returning (context refresh)?
- Should the tangent remain accessible for future reference?
Workflow Integration
- Can I start a tangent mid-operation (while Kiro is running a command)?
- How do I handle tangents in team settings (shared context)?
- Should tangents be saved in session history (for reproducibility)?
- Can I export a tangent as a standalone session (for sharing)?

Thinking Exercise

Trace a Context Pollution Scenario

Before using tangent mode, manually trace how context gets polluted without isolation:

Scenario: Implementing API authentication + debugging CORS issue

WITHOUT TANGENT MODE (polluted context):

Message 1 [Main]: Implement JWT auth for /api/login
Message 2 [Main]: [Kiro implements auth endpoint]
Message 3 [Main]: Test the endpoint with curl
Message 4 [Main]: [Kiro runs curl, gets CORS error]

Message 5 [Detour]: Why am I getting CORS errors?
Message 6 [Detour]: [Kiro explains CORS preflight]
Message 7 [Detour]: Show me the Express CORS config
Message 8 [Detour]: [Kiro shows current config]
Message 9 [Detour]: Update CORS to allow http://localhost:3000
Message 10 [Detour]: [Kiro updates config]
Message 11 [Detour]: Test again with curl
Message 12 [Detour]: [Kiro runs curl, still fails]
Message 13 [Detour]: Check if OPTIONS requests work
Message 14 [Detour]: [Kiro tests OPTIONS]
Message 15 [Detour]: Add Access-Control-Allow-Credentials header
Message 16 [Detour]: [Kiro adds header]
Message 17 [Detour]: Test one more time
Message 18 [Detour]: [Kiro tests, success!]

Message 19 [Main]: OK, now continue with JWT auth
Message 20 [Main]: [Kiro has to re-read context, slowed by CORS noise]

# Problem: Messages 5-18 (14 messages) about CORS pollute the auth implementation context
# Summary would include both auth AND CORS details, losing focus

WITH TANGENT MODE (clean context):

Main Context:
Message 1: Implement JWT auth for /api/login
Message 2: [Kiro implements auth endpoint]
Message 3: Test the endpoint
Message 4: [Kiro runs curl, gets CORS error]
Message 5: [TANGENT: cors-debugging] Fixing CORS issue...
Message 6: [Tangent resolved: Added Access-Control-Allow-Credentials header]
Message 7: Test the fixed endpoint
Message 8: [Kiro tests, success! Continues with auth]

Tangent Context (cors-debugging - ISOLATED):
Message 1: Why am I getting CORS errors?
Message 2-14: [Full CORS debugging session]
Message 15: [Exit: CORS fixed]

# Main context: 8 messages (focused on auth)
# Tangent context: 15 messages (isolated CORS debugging)
# Main summary: "Implemented JWT auth, fixed CORS in tangent"

Questions while tracing:

At what point should you start a tangent (message 5, when you realize CORS is a side issue)?
What information from the tangent is essential for the main context (just the fix, not the debugging process)?
How does the main context “remember” what it was doing before the tangent?
What would happen if you needed to debug CORS again later (can you re-open the tangent)?
How would summarization differ (main context summary vs. full conversation summary)?

Manual test:

# 1. Start a main task
$ kiro "refactor the user service to use TypeScript"

# 2. Notice a side issue (linting error)
# Instead of debugging in-line, start a tangent
$ kiro "start tangent: fix-eslint-config"

# 3. Work in the tangent
$ kiro "why is ESLint complaining about implicit any?"
$ kiro "update tsconfig.json to enable noImplicitAny"

# 4. Exit and return to main
$ kiro "return to main"

# 5. Verify main context is clean
$ kiro "what were we working on?"
# Response: "We're refactoring the user service to TypeScript" (no ESLint details)

The Interview Questions They’ll Ask

Prepare to answer these:

“How do you manage context in a long-running AI agent conversation to prevent focus drift?”
“What is the difference between creating a new chat session and using a tangent within the same session?”
“A developer wants to explore three different implementation approaches for a feature. How would you structure that workflow to keep context clean?”
“How does context summarization work in LLMs, and what information is typically lost during summarization?”
“When would you NOT use a tangent (i.e., when is in-line exploration better)?”
“How do you balance context preservation (keeping everything) with context efficiency (keeping it focused)?”

Hints in Layers

Hint 1: Start Simple Use tangents for clear, isolated sub-tasks: debugging a dependency issue, researching an error message, exploring alternative approaches. Avoid tangents for tasks that are core to the main goal.

Hint 2: Name Tangents Descriptively Use short, descriptive names (e.g., “cors-debugging”, “dependency-conflict”, “api-error-research”). This helps when reviewing session history later.

Hint 3: Explicit Entry and Exit Always explicitly enter and exit tangents with commands like:

kiro "start tangent: investigate-webpack-error"
# [work in tangent]
kiro "return to main"

Hint 4: One-Sentence Summaries When exiting a tangent, summarize the outcome in one sentence:

kiro "tangent resolved: upgraded webpack 4→5, fixed config syntax"

This summary is what gets preserved in the main context.

Books That Will Help

Topic	Book	Chapter
Data Models	“Designing Data-Intensive Applications” by Kleppmann	Ch. 1 (Data Models)
Debugging Strategies	“The Pragmatic Programmer” by Hunt & Thomas	Ch. 7 (Debugging)
Summarization	“Speech and Language Processing” by Jurafsky	Ch. 23 (Summarization)
Cognitive Load	“Thinking, Fast and Slow” by Kahneman	Ch. 8 (Cognitive Effort)
Working Memory	“The Design of Everyday Things” by Norman	Ch. 3 (Knowledge in the Head)
Context Management	“Working Effectively with Legacy Code” by Feathers	Ch. 6 (Code Smells)

Common Pitfalls & Debugging

Problem 1: “I forgot to exit the tangent and continued working in tangent mode”

Why: No explicit “return to main” command was issued.
Fix: Always end tangents with kiro "return to main" or set up an auto-exit after N messages.
Quick test: Check the current mode: kiro "what mode are we in?" (should say “main” or “tangent”)

Problem 2: “Tangent summary is too vague (‘fixed the issue’)”

Why: The summary doesn’t capture what was actually done.
Fix: Write a specific summary: “upgraded jsonwebtoken 8.5.1 → 9.5.2, tests passing” not just “fixed dependency”.
Quick test: Read the summary and ask “Could I reproduce this fix from the summary alone?”

Problem 3: “Main context lost track of what we were doing”

Why: The tangent took too long (> 30 messages), and summarization lost key details.
Fix: Keep tangents short (< 20 messages). For complex issues, create a new top-level session instead.
Quick test: After exiting tangent, ask kiro "what were we working on?" (should recall main task)

Problem 4: “I need information from the tangent in the main context”

Why: The tangent summary was too brief.
Fix: Reference the tangent explicitly: kiro "pull the CORS config from the cors-debugging tangent".
Quick test: Tangents should remain accessible (as sub-sessions) even after exit.

Problem 5: “Nested tangents (tangent within a tangent)”

Why: You started a new tangent while already in tangent mode.
Fix: Avoid nesting. Exit the current tangent first, then start a new one from main.
Quick test: kiro "are we in a nested tangent?" (tool should warn against nesting)

Problem 6: “Tangent mode not available in my Kiro version”

Why: Tangent mode is a newer feature (or not yet implemented in your CLI).
Fix: Use workaround: start a new session with kiro --session tangent-name, exit and return to main session.
Quick test: kiro --version (check if tangent mode is supported)