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