ahoynodnarb/agent-coding-reasoning

Agent & Coding Excellence Skill

This skill encodes best practices for two interrelated capability families:

1. Agentic Tool Use — Precise function/tool calling, multi-turn stateful reasoning, irrelevance detection, and long-horizon task execution
2. Competitive-Grade Coding — Algorithmic problem solving, edge-case correctness, self-repair from execution feedback, and code comprehension

Both families share a common foundation: structured thinking, precise output formatting, and disciplined verification before responding.

---

Part 1 — Agentic Tool Use

Core Philosophy

Tool use is a formal act. A function call is a contract: wrong argument types, missing parameters, or incorrect names cause silent failures or downstream errors. Treat every tool call with the same rigor as writing production code.

The Four Phases of Every Tool Call

Phase 1: Schema Analysis Before calling any tool, fully parse its schema:

• What are the required vs. optional parameters?
• What are the valid types and value ranges for each?
• Are there nested objects? Enums? Constrained strings?
• What does each parameter actually do? (Don't assume from name alone)

Phase 2: Intent–Schema Alignment Map the user's request onto the schema precisely:

• Which user-stated goals correspond to which parameters?
• Are there unstated but necessary parameters (e.g., auth tokens, session IDs)?
• Is the user asking for something outside what the available tools can do? (→ relevance detection)

Phase 3: Call Formation Construct the call:

• Use exact parameter names as specified — no creative renaming
• Match types strictly: don't pass a string where an int is expected, or an array where a scalar is expected
• For optional parameters: include them when they improve precision, omit when genuinely not needed
• Never hallucinate parameters that aren't in the schema

Phase 4: Post-Call Reasoning After a tool returns:

• Check for error signals in the response (status codes, error fields, null results)
• Update your mental model of the current state before proceeding
• Don't assume success — validate the result
• If the result is unexpected, diagnose before calling again

---

Multi-Turn & Stateful Execution

In multi-turn agentic tasks, state accumulates. Managing it well is the single biggest differentiator between agents that complete tasks and agents that loop or fail.

State Tracking Rules:

• After each tool call, explicitly note what changed in the world state
• Keep a mental "current state" summary: what exists, what has been modified, what is still unknown
• Never re-derive state from scratch each turn — carry it forward and update incrementally
• If the task spans many turns, periodically summarize: "Current state: [X]. Remaining steps: [Y]."

Decision-Making Under Uncertainty:

• When a needed parameter is missing from context, first check if a prior tool call result provides it
• If still missing, ask the user for the specific missing value — don't proceed with a hallucinated value
• When two execution paths are both valid, prefer the one that is reversible or lower-risk

Stopping Criteria:

• Stop and report back when: a required function doesn't exist, a required parameter can't be determined, or a prior step failed and proceeding would worsen the situation
• Never loop on the same failed action more than twice without changing strategy

---

Irrelevance Detection

Not every user request should result in a tool call. A sophisticated agent knows when not to act.

Ask yourself:

• Does any available tool actually address the user's need?
• Would calling a tool produce a result that answers the question, or would it be tangential?
• Is the user asking for information or reasoning that I can provide directly, without tool use?

When no tool is appropriate, say so clearly and provide direct assistance instead.

---

Parallel & Multiple Function Calls

When multiple tools can be called independently (results don't depend on each other):

• Identify the full set of independent calls upfront
• Batch them together rather than sequencing unnecessarily
• Note any ordering dependencies explicitly before proceeding

When multiple functions must be called on a single user intent:

• Identify the primary function that addresses the core request
• Identify secondary functions needed to satisfy constraints or produce side effects
• Call them in dependency order

---

Part 2 — Competitive-Grade Coding

Core Philosophy

Correct code is not "code that works on the examples." Correct code is code that works on all valid inputs, including the ones designed to break naive solutions. Think adversarially about your own solutions.

The Algorithm Design Process

Step 1: Understand the problem fully before writing any code

• Re-state the problem in your own words
• Identify the input constraints (size, range, data type)
• Identify the output requirement precisely
• Check example cases to validate your understanding
• Ask: what makes this problem hard? What's the naive approach and why does it fail?

Step 2: Choose the right algorithm class Match the problem structure to the right tool:

• Optimization over choices → Dynamic Programming or Greedy (check exchange argument)
• Graph traversal/reachability → BFS/DFS, Dijkstra, Union-Find
• Ordered data, range queries → Segment Tree, BIT/Fenwick, sorted containers
• String patterns → KMP, Z-algorithm, suffix structures, hashing
• Counting/combinatorics → NTT, generating functions, inclusion-exclusion
• Geometric → convex hull, sweep line, computational geometry primitives
• Brute force feasibility check: if n ≤ ~20, exponential may be fine; if n ≤ ~500, O(n³) may work

Step 3: Analyze complexity before coding

• Time complexity: will this fit within ~10⁸ operations per second?
• Space complexity: will this fit within typical memory limits (~256MB)?
• If not, think again — a clever algorithm is better than an optimized wrong one

Step 4: Code methodically

• Use clear variable names — not a, b, c but left, right, mid
• Handle the base cases and boundary conditions first
• Structure loops and recursion so invariants are obvious
• Use helper functions to decompose complexity
• Prefer correctness over cleverness in implementation

---

Edge Case Discipline

Before finalizing any solution, check all of these:

Input boundaries:

• n = 0 or n = 1 (empty or single-element inputs)
• Maximum n (does the algorithm still terminate efficiently?)
• Minimum and maximum values of elements
• Negative numbers (if allowed)

Structural edge cases:

• All elements identical
• Already sorted / reverse sorted (for sort-based approaches)
• Cycles (for graph problems)
• Disconnected graphs
• Self-loops / multi-edges (if applicable)

Numeric edge cases:

• Integer overflow (use 64-bit integers when products or sums can exceed 2³¹)
• Division by zero
• Floating point precision (prefer integer arithmetic when possible)

Off-by-one errors:

• Array indices: is the loop < n or <= n?
• Range endpoints: inclusive vs. exclusive
• Modular arithmetic: is (a % m + m) % m needed?

---

Self-Repair from Execution Feedback

When given a failing solution and error feedback, use this protocol:

Step 1: Read the error precisely

• What is the error type? (WA, TLE, MLE, RE, CE)
• What is the failing input (if shown)?
• What was the expected output vs. actual output?

Step 2: Categorize the failure

• Wrong Answer (WA): Logic error — trace through the failing case manually, step by step
• Time Limit Exceeded (TLE): Algorithm too slow — identify the bottleneck, rethink complexity
• Memory Limit Exceeded (MLE): Space usage too high — identify large allocations, reduce them
• Runtime Error (RE): Index out of bounds, null dereference, stack overflow — check boundaries
• Compile Error (CE): Syntax error — read the error line carefully

Step 3: Form a hypothesis Name the specific bug before touching the code: "I believe the failure is caused by [X] because [Y]."

Step 4: Fix surgically

• Change only what's needed to fix the identified bug
• Don't rewrite unrelated code — introduce bugs during repair
• After fixing, re-verify all previous passing cases still pass

Step 5: Strengthen the solution After the fix, revisit the edge case checklist. The failing case is often a hint that a class of similar cases is also broken.

---

Code Execution & Output Prediction

When asked to predict or trace program execution:

1. Initialize state: Set all variables to their initial values
2. Execute line by line: Don't skip — each line may have side effects
3. Track mutable state: Arrays, objects, and variables modified in loops need careful tracking
4. Watch for Python-specific behavior: Integer division, list vs. reference semantics, scoping rules
5. Off-by-one in loops: Trace the first and last iteration explicitly
6. Short-circuit evaluation: Boolean operators may not evaluate both sides
7. Return the exact output format: match whitespace, newlines, and type representation exactly

---

Part 3 — Cross-Cutting Principles

These apply to both agentic tasks and coding tasks:

Structured Thinking Before Output

For any non-trivial task, think before you write. Use this structure:

UNDERSTAND: What is actually being asked?
CONSTRAINTS: What are the boundaries/requirements?
APPROACH: What strategy will I use and why?
RISKS: Where could this go wrong?
OUTPUT: Produce the solution, then verify it.

Don't skip the verification step. Re-read your output against the original requirements before finalizing.

Precision in Communication

When the task is ambiguous:

• State your interpretation explicitly: "I'm assuming X means Y."
• If two interpretations lead to very different outputs, ask for clarification
• When you're confident in your interpretation, proceed — don't ask unnecessary clarifying questions

Handling Long or Complex Contexts

When information is spread across a long context:

• Extract and summarize the key facts into a compact working set before starting
• When context contains many similar items (large APIs, many parameters, many records), filter down to only what's relevant to the current step
• Don't let irrelevant context dilute your attention on the important parts

Failure Modes to Actively Avoid

• Parameter hallucination: Inventing tool parameters that don't exist in the schema
• Type coercion mistakes: Passing "3" when 3 is needed
• Premature stopping: Declaring task complete before verifying the end state
• Greedy-trap solutions: Optimizing locally in a way that prevents global optimality
• Untested edge cases: Submitting the first working solution without adversarial testing
• Over-engineering: Adding complexity that isn't needed for the given constraints

---

Quick Reference: At-a-Glance Checklist

Before a Tool Call

• [ ] Read the full schema, not just the parameter names
• [ ] Map user intent to parameters explicitly
• [ ] Check types for every parameter
• [ ] Confirm no required parameters are missing
• [ ] Verify this tool actually addresses the request

Before Submitting Code

• [ ] Does it handle n=0 and n=1?
• [ ] Does it handle max n within time limits?
• [ ] Does it handle all-same values?
• [ ] Are there overflow risks?
• [ ] Are all array accesses within bounds?
• [ ] Does it match the exact output format?

After Execution Feedback

• [ ] Name the bug hypothesis before editing
• [ ] Fix only the identified problem
• [ ] Re-verify all previously passing cases
• [ ] Check the edge case class the failure hints at