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.

| Mode | When | Flow | |------|------|------| | Adversarial | The request matches an adversarial-mode trigger ("debate this", "stress test", "adversarial", "argue for and against", "resource tradeoff", "what would [resource] say"), OR the user has a concrete decision with discrete options and wants to see genuine tension between competing resources. | Skip interactive scoping. Go to Adversarial Flow below. | | Interactive (default) | Anything else — exploratory thinking, "help me think through", open-ended decisions, when the user wants to be in the loop. | Continue to Step 2-Interactive (Scope the Discussion). |

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 "" "" 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):

| Style | Description | |-------|-------------| | Socratic | I ask questions, you discover answers. Best for early exploration. | | Direct | I provide structured analysis and observations. Best for experienced builders. | | Framework-Guided | I walk you through a specific thinking framework step by step. Best for complex decisions. |

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/:

| Problem Pattern | Framework | Reference | |----------------|-----------|-----------| | Binary/multi-option choice | Decision Matrix | references/frameworks/decision-matrix.md | | Challenging assumptions | First Principles | references/frameworks/first-principles.md | | Risk assessment | Pre-Mortem | references/frameworks/pre-mortem.md | | Ripple effects analysis | Consequence Mapping | references/frameworks/consequence-mapping.md | | Stress-testing a preference | Devil's Advocate | references/frameworks/devils-advocate.md | | Comparing 3+ options | Option Evaluation Rubric | references/frameworks/option-evaluation-rubric.md |

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:

| If the discussion produced... | Suggest | |-------------------------------|---------| | Architecture or technology decision | /shipkit-engineering-definition — to log the decision with rationale | | Feature requirements or scope | /shipkit-spec — to formalize into a specification | | Implementation approach | /shipkit-plan — to create an actionable plan | | Project vision or strategy | /shipkit-why-project — to update project vision | | Data model or contract decisions | /shipkit-engineering-definition — to define in engineering blueprint | | Risk assessment or launch criteria | /shipkit-preflight — to track readiness |

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stefan-stepzero
• Source: stefan-stepzero/shipkit
• License: MIT

Install and usage instructions live in the source repository linked above.