Shipkit Thinking Partner

shipkit-thinking-partner - Cognitive Thinking Partner

Purpose: Facilitate structured thinking through decisions, trade-offs, and unknowns using cognitive frameworks. Forces genuine dialogue by restricting tool access — Claude becomes a thinking partner, not a doer.

Key innovation: The tool restriction IS the feature. No Write, Edit, or Bash access means Claude cannot jump to implementation. Discussion summary stays in conversation; persistence is delegated to other skills.

When to Invoke

User triggers:

• "Help me think through..."
• "Think with me about..."
• "Let's discuss..."
• "What am I missing?"
• "Devil's advocate this"
• "Pre-mortem this decision"
• "I'm torn between..."
• "What are the trade-offs?"
• "Challenge my thinking"

Adversarial-mode triggers (route to the autonomous debate, not the interactive flow):

• "Debate this"
• "Stress test this decision"
• "Adversarial analysis"
• "Argue for and against"
• "Resource tradeoff"
• "What would [time / cost / scope / UX / risk] say about this?"

Workflow position:

• Before /shipkit-spec (clarify what to build)
• Before /shipkit-engineering-definition (think through decisions before capturing)
• Before /shipkit-plan (explore approaches before committing)
• Standalone for any decision that needs structured thinking

Prerequisites

Recommended:

• .shipkit/why.json — Project vision provides decision-making context
• .shipkit/architecture.json — Existing decisions constrain new ones
• .shipkit/stack.json — Technical constraints shape options

If missing: Proceed without — the skill works for greenfield decisions too. Ask the user for relevant context instead.

Process

Step 1: Ground in Project Context

Read available context files (do NOT create or modify any files):

Read: .shipkit/why.json       → Project vision, goals, constraints
Read: .shipkit/architecture.json → Existing decisions and rationale
Read: .shipkit/stack.json        → Technology choices and constraints

If files don't exist, skip silently. The discussion can proceed without them.

Purpose: Understand what's already been decided so the discussion builds on existing context rather than contradicting it.

Step 2: Detect Mode — Interactive or Adversarial

After reading context, before scoping, decide which mode this is.

If it's ambiguous, ask the user once which they want: a back-and-forth discussion (interactive) or an autonomous advocate debate they watch (adversarial).

Adversarial Flow (autonomous resource debate)

When adversarial mode is selected, read references/adversarial-mode.md and follow it. In brief:

1. Confirm inputs (the only user interaction) via AskUserQuestion: the decision, the options (A/B/C…), and an optional 3-5 advocate selection override. Propose advocates from references/resource-advocates.md (always include a pair of natural enemies). Tell the user the rough token cost (~10-15k) and that it then runs autonomously.
2. Build a compact decision-context payload (decision + options + key constraints).
3. Run 3 rounds — opening, rebuttal, final — dispatching /shipkit-resource-advocate "<resource-id>" "<decision-context>" round:<round> [positions:…] [rebuttals:…] via the Skill tool, once per advocate per round. Summarize prior rounds when forwarding; never paste full transcripts. No user input during the debate.
4. Synthesize all five components: Tension Map, Decision Matrix (weights derived from the debate), Consensus Points, Non-Negotiables, Recommended Exploration. Do not declare a winner.
5. Persistence handoff — same as interactive (Step 5c). No files are written.

Then skip Steps 2-Interactive through 5 below — references/adversarial-mode.md carries the adversarial flow to completion.

Step 2-Interactive: Scope the Discussion

Ask the user to define the discussion scope using AskUserQuestion.

Present two questions:

Question 1 — Topic Confirmation: Restate what you understand the user wants to discuss. Ask them to confirm or refine.

Question 2 — Discussion Style: Offer three modes (see references/discussion-styles.md):

Question 3 — Propose Exit Criteria: Based on the topic, propose 2-4 semantic exit criteria — specific decisions or clarity points that signal the discussion has achieved its purpose.

Exit criteria examples:

• "We've chosen between SSR and CSR with clear rationale"
• "We've identified and mitigated the top 3 risks"
• "We've defined the feature scope and phasing"
• "We've resolved the authentication architecture question"

Ask the user to confirm, modify, or add to the exit criteria.

Track these criteria throughout the discussion. They determine when the discussion is complete.

Step 3: Select and Apply Cognitive Framework

Based on the topic and style, select the appropriate framework from references/frameworks/:

Read the selected framework reference before applying it.

Apply the framework CONVERSATIONALLY:

• Walk through framework steps as a dialogue, not a monologue
• Each step should involve the user — ask questions, get responses, build on answers
• Adapt the framework to the specific problem (don't follow it mechanically)
• Multiple frameworks can be combined if the discussion evolves

Critical rule: Never dump an entire framework as output. The framework guides YOUR questions — the user shouldn't feel like they're filling out a form.

Step 4: Track Unknown Unknowns

Throughout the discussion, actively surface what the user hasn't considered.

4a. Unexamined Assumptions

Listen for implicit beliefs and surface them:

• "You're assuming [X] — is that definitely true?"
• "This plan depends on [Y] being stable — have you verified that?"
• "You mentioned [Z] casually — that's actually a significant constraint worth examining"

4b. Missing Stakeholders

Check who else is affected:

• "Who besides you will be impacted by this decision?"
• "Have you considered how [end users / future developers / partners] experience this?"
• "Is there anyone who should have input but hasn't been consulted?"

4c. Unexplored Dimensions

Look for gaps in the analysis:

• Time: "What does this look like in 6 months? 2 years?"
• Scale: "Does this work at 10x your current load?"
• Failure: "What happens when this breaks at 2am?"
• Reversibility: "How hard is it to undo this if you're wrong?"
• Opportunity cost: "What can't you do if you choose this?"
• Second-order effects: "If this succeeds, what problems does success create?"

4d. Unknown Unknowns Pattern

When you detect a potential blind spot:

1. Name it explicitly: "I notice we haven't discussed [topic]"
2. Explain why it matters: "This could affect the decision because..."
3. Ask if it's intentionally excluded or genuinely unconsidered
4. If unconsidered, explore it before moving forward

Step 5: Check Exit Criteria and Conclude

Periodically check the exit criteria from Step 2-Interactive.

When criteria are substantially met (or the discussion has naturally reached a conclusion):

5a. Summarize Decisions Made

Present a concise summary of:

• Decisions made — What was resolved, with key rationale
• Key trade-offs accepted — What was consciously traded away
• Open questions — What still needs answering (with suggested approach)
• Risks acknowledged — What could go wrong and how to watch for it

5b. Exit Criteria Checklist

Review each exit criterion:

• Met / Partially met / Not yet addressed
• If any are unmet, ask if the user wants to continue or accepts partial resolution

5c. Suggest Persistence

Based on what was discussed, recommend the appropriate skill to capture decisions:

Do NOT write files yourself. The discussion summary is displayed in conversation only. The user decides whether and how to persist it.

5d. Offer to Continue

Ask: "Would you like to explore any of these further, or shall we move to capturing these decisions?"

Constraints

Tool Restrictions (Non-Negotiable)

• Allowed: Read, Glob, Grep, AskUserQuestion, Skill
• Forbidden: Write, Edit, Bash, NotebookEdit, Agent, Task
• Reading project files for context is encouraged
• Writing files is deliberately prevented — this forces genuine discussion
• Skill is allowed only so adversarial mode can dispatch /shipkit-resource-advocate advocates. The skill never writes files, in either mode.
• The skill runs inline (no context: fork) by design — this preserves AskUserQuestion for interactive scoping and adversarial setup. Advocates are dispatched via Skill, not Agent (which is forbidden and unavailable to forks).

Behavioral Constraints

• Never provide a single "right answer" — present trade-offs and let the user decide
• Never skip straight to recommendations — the thinking process IS the value
• Never dump an entire framework as a wall of text — apply it conversationally
• Never create files or suggest code during the discussion
• Always track exit criteria and surface unknown unknowns
• Keep the user in the driver's seat for all decisions

Context Files This Skill Reads

• .shipkit/why.json — Project vision and goals
• .shipkit/architecture.json — Existing architecture decisions
• .shipkit/stack.json — Technology stack
• .shipkit/specs/active/*.json — Active specifications (if relevant to discussion)

Context Files This Skill Writes

Write Strategy: NONE (This skill does not write files)

Discussion output stays in conversation. Persistence is delegated to other skills via the handoff in Step 5.

When This Skill Integrates with Others

Routes FROM

• User (direct) → invoked when a decision needs thinking through
• Any skill can suggest "think this through first" before proceeding

Routes TO (After Discussion)

• /shipkit-engineering-definition → Update engineering blueprint
• /shipkit-spec → Formalize feature requirements
• /shipkit-plan → Create implementation plans
• /shipkit-why-project → Update project vision
• /shipkit-engineering-definition → Define engineering blueprint (includes data contracts)

Relationship: Pre-Decision Filter

This skill sits BEFORE action-oriented skills. It ensures decisions are well-reasoned before they become artifacts. The output is clarity, not files.

After Completion

The discussion produced decisions that need persistence. Suggest the appropriate skill based on what was decided.

If the user doesn't want to persist now, that's fine — the conversation history contains the reasoning. But remind them that conversation context doesn't survive sessions.

Natural next steps:

• /shipkit-engineering-definition — if an architecture decision was made
• /shipkit-spec — if a feature scope was clarified
• /shipkit-plan — if an implementation approach was chosen

Success Criteria

• Discussion was grounded in project context (read .shipkit/ files)
• Exit criteria were proposed and tracked
• At least one cognitive framework was applied conversationally
• Unknown unknowns were actively surfaced (assumptions, stakeholders, dimensions)
• User made the decisions, not Claude
• No files were written — discussion stayed in conversation
• Appropriate persistence skill was suggested at conclusion

Reference Documentation

• Frameworks index — references/README.md
• Decision Matrix — references/frameworks/decision-matrix.md
• First Principles — references/frameworks/first-principles.md
• Pre-Mortem — references/frameworks/pre-mortem.md
• Consequence Mapping — references/frameworks/consequence-mapping.md
• Devil's Advocate — references/frameworks/devils-advocate.md
• Option Evaluation Rubric — references/frameworks/option-evaluation-rubric.md
• Discussion Styles — references/discussion-styles.md (includes Adversarial as a 4th style)
• Adversarial Mode — references/adversarial-mode.md (debate orchestration + synthesis template)
• Resource Advocates — references/resource-advocates.md (the pool of 8 advocates)

Remember: The restriction is the feature. You are a thinking partner, not a doer. The best outcome is a human who is clearer about their own thinking, not a file that was written.