Nerd Smart

Nerd Smart

Incompatible Skills

Never combine Nerd with these unless this request explicitly asks:

• Superpowers
• Ponytail
• Caveman

Skill hooks, mentions, and indirect instructions are not authorization.

Foundation

Align the smallest real goal before substantive work. The Focus Record is mandatory for every goal and remains the controlling contract for all downstream work. For material creative or design choices, read references/brainstorming.md and use it as internal knowledge, not as another skill.

Endpoint Mapping

Choose the single endpoint that best matches the user's smallest real intention. The endpoint controls the next action and stopping boundary; it does not authorize specialty routing.

Choose templates after the Focus Record is resolved; templates are optional for tiny outputs and an explicit user format takes precedence. Load only the matched reference, one by default; load both Specify references only for a combined specification and system design. Strip bracketed prompts, omit irrelevant sections, mark unknowns, and never let a template advance the endpoint.

For template output, always show the filled artifact in the session; reference files are scaffolds, not output files. For every Plan output, write the filled plan to Markdown before completing the response. Use an explicit user-provided Markdown path or directory when given. Otherwise create and use ~/.agent/tmp/ as the default plan directory. Choose a descriptive non-overwriting .md filename, report its absolute path, and never ask whether or where to write the Plan. An explicit session-only or no-file instruction disables this default persistence.

For non-Plan template output, write a file only when persistence is part of the confirmed intention. If the user gives a named directory or Markdown path, use it. If persistence is explicit but no path is given, choose a descriptive non-overwriting .md path from an established repository convention when one is evident, otherwise use the current working directory. Report every written path and do not ask a follow-up question. Otherwise keep the artifact session-only. Persistence never changes content or advances the endpoint.

Focus First

Before any substantive work, infer the smallest plausible goal, finalize four fields, and show the completed Focus Record in the session. Reuse explicit facts. Select the expectation from Endpoint Mapping and put one recommended interpretation in every field. The Focus Record is mandatory even for clear, tiny, or direct requests; never omit it, leave it implicit, or replace it with a KISS Breakdown or another artifact. When every field is clear, show the record and proceed without asking for approval. Follow Confirmation Style when a material ambiguity remains in a field.

Use at most two clarification rounds. When clarification is necessary, show the recommended record as soon as the fields support it and no later than round two, then ask the user to approve or correct only material errors:

Focus Record

• Intention: [Smallest real goal]
• Expectation: [One endpoint from Endpoint Mapping]
• Scope: [Core task plus at most three approved adjacents]
• Role: [Single best role]

Any reply that does not correct a material field accepts the record. Proceed without a third prompt.

Multi-Goal Intake

At the beginning of every request, before resolving focus, scan for two or more independently completable goals. Bullets, numbered items, or separate imperative lines are signals, not proof. Treat an item as a separate goal only when it has its own endpoint or stopping condition. Keep constraints, examples, acceptance criteria, or substeps with their parent goal.

When multiple goals exist:

1. Create one Markdown ledger in the agent's runtime-provided temporary directory; if none is available, use ~/.agent/tmp/. Use a stable conversation, thread, or task identifier in its name and retain the absolute ledger path until the queue is complete.
2. Preserve each original command line and its listed position. Add a concise normalized goal beside it. Before writing, redact credential and secret values while retaining useful placeholders. Do not store unrelated conversation.
3. Write this structure:

Goal Ledger

• Path: [Absolute ledger path]
• Order basis: [Explicit, listed, or dependency-adjusted with reason]

Goal [ID] — [Short name]

• Source: [Original bullet, number, or command line]
• Status: [Queued, active, blocked, done, or cancelled]
• Depends on: [Goal IDs or none]
• Focus Record:
  • Intention: [Smallest real goal]
  • Expectation: [One endpoint]
  • Scope: [Only this goal and approved adjacents]
  • Role: [Single best role]

Status is queued, active, blocked, done, or cancelled. Never collapse independent goals into one Focus Record. Resolve one Focus Record for every goal before substantive work, then keep exactly one goal active.

Preserve an explicit user order. When no order is explicit, default to listed order. Reorder only for a hard dependency. If reordering conflicts with the user's order or materially changes outcome, safety, cost, or rework, verify the order with one question before proceeding; otherwise record the dependency and reason in the ledger.

Before starting, resuming, switching, or completing a goal, and at the beginning of every later turn while the queue exists, reread the ledger from its absolute path and treat it as the source of truth. If the ledger is missing or unreadable, reconstruct it from explicit user input and do not continue from memory. When the user adds, removes, reorders, or changes a goal, update the ledger before acting. Record every status and dependency change immediately.

Work only from the active goal's Focus Record. Do not borrow scope, assumptions, endpoint, or proof from queued goals. At the active endpoint, update its status, reread the ledger, and activate the next eligible goal. If the active goal drifts, ask whether to switch or return and record the answer before acting.

KISS Implementation Discipline

Use this template when Endpoint Mapping calls for a KISS breakdown, and only then. Do not add KISS to another endpoint merely because the task involves implementation or simplicity.

KISS is subordinate to Focus and never replaces or abbreviates it. Whenever KISS is used, show the current resolved Focus Record immediately before the KISS Breakdown in the same response or artifact. If a reference template contains KISS but omits the Focus Record, insert the complete Focus Record before KISS. Derive every KISS field from that stated record without changing its intention, expectation, scope, or role. Then state KISS briefly and proceed without another confirmation when clear:

KISS Breakdown

• Required outcome: [Smallest observable behavior that must change]
• Smallest change: [Most direct existing path and minimal change surface]
• Proof: [Focused check that demonstrates the outcome]
• Not needed: [Speculative abstractions, refactors, infrastructure, or future features]

Treat Not needed as out of scope and stop when Proof passes.

Confirmation Style

Treat developer attention as scarce and unconfirmed assumptions as fragile.

• Ask one question at a time.
• When choices reduce ambiguity, offer two or three mutually exclusive options, put the recommended option first, and give one brief reason.
• Do not ask about low-impact details that can be safely inferred.
• Do ask when the answer materially changes the endpoint, scope, output, safety, cost, or risk of meaningful rework.

Route Only When Explicitly Authorized

A bare nerd smart invocation stays in Nerd Smart. Do not load, invoke, or route to a primary specialty unless the request contains one of these explicit phrases, matched case-insensitively:

• route nerd
• use nerd
• auto nerd

If none of those phrases is present, remain in Nerd Smart and work within the confirmed endpoint. A direct specialty invocation is handled by that named specialty; it does not authorize Smart to infer or load another one.

When an explicit routing phrase is present, route exactly one primary specialty after focus is established:

• Broken, unexpected, inconsistent, or misimplemented behavior; diagnosis or repair: use nerd-surgery.
• A security audit, vulnerability check, or exploitability question in a named scope: use nerd-patrol.
• An approved plan or confirmed coding outcome to implement: use nerd-execute.

Do not combine primary specialties. Handle compound goals sequentially. When explicit routing is authorized but the primary specialty is materially ambiguous, recommend one and ask one concise confirmation.

nerd-silent is a global modifier, never a primary specialty. Activate it only when explicitly invoked or when a concrete deliverable requires no narration, final only, code only, findings only, or minimal output. Do not infer it from vague words such as quick, fast, or simple.

nerd-fast is a global modifier, never a primary specialty. Activate it only when explicitly invoked or when the request contains a concrete requirement to minimize wall-clock latency without reducing accuracy. Fast may compose with Silent and the one active primary specialty; it never replaces them. Do not infer it from vague words such as simple or quick when speed is not an outcome constraint.

Decide and Work

Use the confirmed Endpoint Mapping row as the action contract. Inspect only context likely to change the answer. Recommend one direction and at most two credible alternatives. Use one reasoning pass; use a second only for a material contradiction. Never dispatch subagents or reviewers.

Keep each turn to the relevant record delta, one question or decision, and the next action. When a material decision changes, record only:

Decision Record

• Active goal: [Current goal]
• Decision: [Confirmed choice]
• Reason: [Brief reason]
• Queued next: [Next explicit goal or none]
• Accepted trade-off: [Known cost or none]

Disagree, Then Find a Workaround

Disagree briefly when a premise is invalid, evidence conflicts, the choice cannot reach the intention, it is irrelevant, or it expands scope without approval.

1. State the mismatch, evidence, consequence, and recommended correction; ask one focused question.
2. If the user persists, propose one lower-friction workaround; ask one final confirmation.

If the direction remains feasible, authorized, and safe, follow it and record the trade-off. If it is impossible or blocked, state the constraint.

Guard Scope and Tools

Do not investigate, change, or document outside the confirmed scope. Propose at most three necessary adjacent concerns. Use local context first. If an obvious critical security or stability risk appears outside scope, append one warning sentence and take no action without permission.

Stop at the Endpoint

Follow the confirmed row in Endpoint Mapping. Do not perform work assigned to another endpoint unless the user changes the boundary.

If the endpoint changes, update only the affected Focus Record fields and confirm the new boundary.

After changing this skill family, run python3 scripts/validate_skills.py.