Skill: hongyi3/socrates (version 0.1.1)

--- name: socrates description: Use when an agent is about to plan, choose an approach, do non-trivial coding, refactor, decompose work, or delegate and the quality of execution depends on exposing assumptions before acting. Run a concise Socratic self-Q&A to clarify the goal, surface unknowns, pressure-test risks, choose an approach, and define the next action. Default to one round and open a second round only when risk, ambiguity, missing constraints, or live tradeoffs remain unresolved. --- # Socrates Use this skill to think before acting. It should improve execution quality, not turn the response into abstract philosophy or slow every task down. ## Quick Trigger Guide Use Socrates for: - plan creation and sequence design - architecture choices or risky implementation decisions - refactors with a non-trivial blast radius - delegation to one or more sub-agents Skip or compress Socrates for: - trivial chat - direct translation - formatting-only edits - fully specified micro-fixes with almost no rework risk ## Core Protocol 1. Decide whether to skip, compress, or run the full pass. 2. Run Round 1 before planning, coding, or delegation: - What is the real goal and what counts as done? - What is known, what is unknown, and which assumptions am I making? - What is most likely to fail, waste time, or force rework? - Which approach is best, and why am I rejecting the main alternatives? - What should happen next, and what should be delegated? 3. Open Round 2 only if a trigger still applies after Round 1: - The task includes an architecture-level or hard-to-reverse decision. - Key constraints are missing and acting now is likely to cause rework. - Multiple sub-agents will be involved and boundaries are still fuzzy. - Two or more plausible approaches remain live and the tradeoff is not settled. 4. Keep Round 2 narrow. Ask only the unresolved follow-up questions; do not repeat the full pass. 5. Produce the final sections in order: - `Socratic Pass` - `Action Plan` - `Delegation Contract` only when sub-agents are involved ## Compression Rules - Skip the full pass for trivial chat, direct translation, formatting-only edits, or fully specified micro-fixes. - Use a compressed one-round pass for simple but still important work. - Keep the default experience short. Most tasks should finish in one round. ## Delegation Rules - Run the parent pass before spawning sub-agents. - In each handoff, include: - goal - done criteria - constraints - deliverable - explicit instruction to run a mini Socratic pass before acting - Require each sub-agent to surface assumptions, the main risk, the chosen approach, and the immediate next step before execution. ## Guardrails - Do not write abstract philosophy. - Do not restate the user request at length. - Do not force a second round by default. - Do not use self-reflection instead of asking the user for clarification when a blocking unknown remains. ## References - Read `references/protocol.md` for the detailed protocol, templates, and delegation contract. - Read `references/examples.md` for planning, coding, and delegation examples.

path: LICENSE.txt
content: MIT License

Copyright (c) 2026 Hongyi3

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


path: agents/openai.yaml
content: interface:
  display_name: "Socrates"
  short_description: "Pressure-test plans before coding or delegation"
  icon_small: "./assets/icon-small.svg"
  icon_large: "./assets/icon-large.svg"
  brand_color: "#0F766E"
  default_prompt: "Use $socrates to pressure-test this task before planning, coding, or delegation, then continue with the chosen approach."
policy:
  allow_implicit_invocation: true


path: assets/icon-large.svg
content: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Socrates logo">
  <defs>
    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#0f766e"/>
      <stop offset="100%" stop-color="#134e4a"/>
    </linearGradient>
    <linearGradient id="card" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#f0fdfa"/>
      <stop offset="100%" stop-color="#ccfbf1"/>
    </linearGradient>
  </defs>
  <rect width="512" height="512" rx="96" fill="url(#bg)"/>
  <rect x="86" y="94" width="340" height="210" rx="36" fill="url(#card)"/>
  <path d="M150 376l60-52h132c46 0 84-38 84-84V160c0-46-38-84-84-84H170c-46 0-84 38-84 84v80c0 46 38 84 84 84h18z" fill="#99f6e4" opacity="0.58"/>
  <path d="M220 196c0-37 27-64 64-64s64 27 64 64c0 25-14 40-29 54-14 13-27 25-27 48" fill="none" stroke="#115e59" stroke-linecap="round" stroke-width="24"/>
  <circle cx="256" cy="334" r="18" fill="#115e59"/>
  <text x="256" y="448" text-anchor="middle" font-family="Menlo, Monaco, Consolas, monospace" font-size="56" fill="#ecfeff">SOCRATES</text>
</svg>


path: assets/icon-small.svg
content: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="Socrates icon">
  <defs>
    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#0f766e"/>
      <stop offset="100%" stop-color="#134e4a"/>
    </linearGradient>
  </defs>
  <rect width="128" height="128" rx="28" fill="url(#bg)"/>
  <rect x="20" y="22" width="88" height="58" rx="14" fill="#f0fdfa" opacity="0.95"/>
  <path d="M40 96l18-16h34a12 12 0 0 0 12-12V44a12 12 0 0 0-12-12H36a12 12 0 0 0-12 12v24a12 12 0 0 0 12 12h4z" fill="#ccfbf1"/>
  <path d="M52 49c0-7 5-12 12-12s12 5 12 12c0 5-3 8-6 11-3 3-5 5-5 10" fill="none" stroke="#115e59" stroke-linecap="round" stroke-width="8"/>
  <circle cx="64" cy="82" r="5" fill="#115e59"/>
</svg>


path: references/examples.md
content: # Socrates Examples

These examples show the expected tone and shape. Keep the reasoning compact and action-oriented.

## Planning Example

### Request

Plan a migration from a single API service to separate read and write services.

### Response Shape

```md
Socratic Pass
Round 1
- Goal and done criteria: Produce a migration plan that splits read and write traffic without breaking current clients.
- Knowns, unknowns, assumptions: I know the current service boundary and expected traffic pattern. I do not yet know deployment constraints or rollback limits. I assume the API contract should remain stable in v1.
- Risks: Client breakage, dual-write inconsistencies, and an unclear rollback path.
- Chosen approach: Plan an incremental split behind a stable interface, instead of a full rewrite, because it reduces migration risk.
- Next actions and delegation: Map current boundaries, define a phased rollout, then assign interface validation and data consistency checks if sub-agents are available.

Action Plan
1. Inventory the current responsibilities and stable contracts.
2. Define the target read and write boundaries plus rollback strategy.
3. Sequence rollout phases and validation checkpoints.
```

## Coding Example

### Request

Add request rate limiting to a public API endpoint before implementing the code change.

### Response Shape

```md
Socratic Pass
Round 1
- Goal and done criteria: Add rate limiting that protects the endpoint without breaking expected client behavior.
- Knowns, unknowns, assumptions: I know the endpoint and likely middleware layer. I do not yet know per-tenant versus global limits. I assume we need a safe default and observability.
- Risks: Choosing the wrong scope, causing false positives, or adding state in the wrong layer.
- Chosen approach: Implement a middleware-based limiter with explicit configuration points because it keeps the change localized and testable.
- Next actions and delegation: Confirm the limit model, identify the middleware entry point, then implement and test.

Action Plan
1. Confirm the intended limit scope and fallback behavior.
2. Add the limiter in the request pipeline.
3. Test normal traffic, bursts, and error responses.
```

## Delegation Example

### Request

Split a feature delivery task across a frontend sub-agent and a backend sub-agent.

### Response Shape

```md
Socratic Pass
Round 1
- Goal and done criteria: Deliver the feature with aligned UI behavior and API support.
- Knowns, unknowns, assumptions: I know the feature goal and the likely frontend and backend touchpoints. I do not yet know the final payload shape. I assume we can lock an interface before parallel work starts.
- Risks: Mismatched contracts, duplicated effort, and late integration failures.
- Chosen approach: Define the shared contract first, then delegate implementation tracks in parallel.
- Next actions and delegation: Write the interface contract, spawn frontend and backend sub-agents with the same contract, then review integration results.

Action Plan
1. Define the shared API and UI expectations.
2. Delegate implementation with the same constraints and deliverable format.
3. Reconcile integration gaps and run final verification.

Delegation Contract
- Goal: Implement one side of the agreed feature contract.
- Done criteria: Your change matches the shared contract and reports any mismatch immediately.
- Constraints: Do not change the contract without surfacing it. Run Socrates first.
- Deliverable: Short summary, changed files, tests run, blockers.
- Run Socrates first: Perform a concise mini pass before acting and use Round 2 only if a material ambiguity remains.
```

## High-Risk Round 2 Example

Use a second round only when the first round still leaves a major decision open.

```md
Socratic Pass
Round 1
- Goal and done criteria: Choose a caching strategy for a high-traffic endpoint.
- Knowns, unknowns, assumptions: I know the traffic profile but not the invalidation guarantees required by downstream consumers.
- Risks: Serving stale data or adding an invalidation path we cannot support.
- Chosen approach: No final choice yet. Two options remain viable: TTL cache and event-driven invalidation.
- Next actions and delegation: Run Round 2 on invalidation guarantees before planning implementation.

Round 2
- Trigger: Two plausible approaches remain live and the tradeoff is not settled.
- Follow-up question(s): What freshness guarantees are actually required, and can the current system emit reliable invalidation events?
- Resolution: If strong freshness is required and events are reliable, prefer event-driven invalidation. Otherwise choose TTL caching with explicit freshness limits.

Action Plan
1. Confirm freshness guarantees.
2. Select the caching strategy based on that answer.
3. Implement observability and rollback hooks.
```


path: references/protocol.md
content: # Socrates Protocol

Use this protocol to improve thinking quality before acting. Prefer one round. Open a second round only when the first round still leaves a material decision unresolved.

## Decision Gate

Choose one of these entry modes before doing any real work:

- Skip: casual chat, direct translation, formatting-only edits, or fully specified micro-fixes.
- Compressed Round 1: bounded work that still matters, such as a small code change with a clear target and a modest blast radius.
- Full Round 1: planning, architecture, non-trivial coding, refactors, task decomposition, or delegation.

## Round 1

Answer these five questions in order. Keep each answer short and concrete.

1. Goal and done criteria
   - What problem am I solving?
   - What would count as a successful result?
2. Knowns, unknowns, and assumptions
   - What facts do I already have?
   - What important details are missing?
   - Which assumptions am I making for now?
3. Risks and failure modes
   - What is most likely to fail?
   - What would cause rework, wasted effort, or hidden regressions?
4. Approach selection
   - Which approach should I use?
   - Why is it better than the main alternatives for this task?
5. Next actions and delegation
   - What should happen now?
   - What should be delegated, if anything?
   - In what order should the work move?

## Round 2

Run a second round only when Round 1 still leaves a high-impact decision unresolved.

### Triggers

- The task includes an architecture-level or hard-to-reverse decision.
- Key constraints are missing and acting now is likely to cause rework.
- Multiple sub-agents are needed and ownership or interfaces are still unclear.
- Two or more plausible approaches remain live and the tradeoff is not settled.

### Round 2 rules

- Ask only the follow-up questions needed to close the decision gap.
- Do not repeat all five Round 1 questions.
- Stop after the key uncertainty is resolved or clearly surfaced to the user.

## Output Contract

Use this section order:

```md
Socratic Pass
Round 1
- Goal and done criteria: ...
- Knowns, unknowns, assumptions: ...
- Risks: ...
- Chosen approach: ...
- Next actions and delegation: ...

Round 2
- Trigger: ...
- Follow-up question(s): ...
- Resolution: ...

Action Plan
1. ...
2. ...
3. ...

Delegation Contract
- Goal: ...
- Done criteria: ...
- Constraints: ...
- Deliverable: ...
- Run Socrates first: ...
```

### Section rules

- Always include `Socratic Pass`.
- Always include `Action Plan`.
- Include `Delegation Contract` only when sub-agents are involved.
- Include `Round 2` only when a real trigger fired.
- Keep the whole response compact. Most tasks should complete with Round 1 only.

## Delegation Contract

Use this handoff shape when work moves to a sub-agent:

```md
Goal:
Done criteria:
Constraints:
Deliverable:
Run Socrates first:
- Do a concise mini Socratic pass before acting.
- Use a second round only if risk or ambiguity remains unresolved.

Report back:
- Socratic Pass
- Action taken
- Results or blockers
```

## Mini Pass For Child Agents

Require every child agent to answer these before taking action:

1. What is the goal and what counts as done?
2. What is known, unknown, and assumed?
3. What is the main risk?
4. What approach will I use?
5. What is the immediate next step?

Keep the child pass short. Default to one round.

## Anti-Patterns

- Do not turn the pass into abstract philosophy.
- Do not repeat the user request in different words.
- Do not generate a second round just to look thorough.
- Do not hide blocking uncertainty inside self-reflection; ask the user when needed.
- Do not let the pass replace real execution. It should sharpen action, not delay it.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)