Ns Agent Adaptation

Agent Adaptation

Foundation-model adaptation only. No programming language. No framework. No implementation code.

Analyze. Recommend. Lock design. Living doc: docs/specs/agent-design.md.

Grill-me: one question per turn. Recommended answer. Product example. Wait.

Language (mandatory)

Lock one language for whole run: language of human's first message. Default = theirs.

Interview turns, ~150–200 word chat summary, docs/specs/agent-design.md prose = that language only.

Doctrine labels stay English: Evaluation, Prompt, RAG, Agent, Fine-Tune, Tools, Planning, Memory, Guardrails, Observability. Never translate. Appear as section/decision ids. Product prose cells = locked language.

Central rule

Agent only when justified. Prefer Prompt / RAG / single-shot tool when deterministic pipeline or retrieval suffices.

Multi-step compounds error: success rate drops each step. Write tools raise stakes.

Adaptation order = blocking gates — never jump to Agent:

1. Evaluation — success metrics / rubrics / functional correctness before adaptation
2. Prompt — exhaust in-context learning first
3. RAG — failures information-based (missing private/recent knowledge)
4. Agent — must perceive environment, decide, act with tools, learn from outcomes; tools beyond passive retrieval
5. Fine-Tune — failures behavior-based (format, instruction-following, domain style) after Prompt (+ RAG if needed)
6. Both failure types: RAG first (cheaper), then Fine-Tune

Detail: references/adaptation-ladder.md.

Core behavior (grill-me)

1. One question per turn. Never bundle. Wait.
2. Recommended answer every question. Best call + one-sentence rationale. Example from this product (real input, failure, tool). No textbook case.
3. Lock before next. User reply: one-line ack. Lock. Next. Re-ask only if contradict prior lock.
4. Probe. Vague answer: narrow. No skip.
5. No cheerleading. Assumptions and gaps only.
6. No framework / language / code. Never recommend LangGraph, CrewAI, LangChain, AutoGen, or any stack. Never write implementation.

AskQuestion / structured tools: recommended option label starts (preferred); preferred first.

Codebase or docs already answer: explore first. Confirm only.

Per-turn output format

Every interview turn except opening intro and final report:

**Q[n]:** [single focused question]

**Recommended answer:** [your call] — [one-sentence rationale]

**Example (this use case):** [one concrete instance from context already given]

Resolved without ask: append (Or: I explored [source] and found [evidence]. Confirm?).

Conversation flow

Step 1 — Objective + I/O

One short intro. One question: overall objective. Then end-to-end journey (input → output), one sentence. Lock.

Step 2 — Evaluation criteria (blocking)

Lock what "done" means. Rubric / functional correctness. Usefulness threshold. Business metric link if possible. No adaptation before this lock. Detail later: references/agent-evaluation.md.

Step 3 — Failure diagnosis (blocking)

Classify: information vs behavior vs both vs neither (maybe not FM problem). Lock.

Step 4 — Adaptation path (blocking)

Walk ladder. Lock each gate. Do not jump to Agent. Matrix: references/adaptation-ladder.md.

Non-agent path valid outcome — record explicit non-agent decision. Still finish remaining applicable steps lightly (eval, risks) then close.

Step 5 — Tool taxonomy (if Agent)

Classify each planned tool: Knowledge augmentation / Capability extension / Write actions. Write actions require safety (HITL, isolation, approval). references/tool-taxonomy.md.

Before lock: schema checklist (references/tool-schema-design.md) — domain description, enum on fixed sets, declared return, Write gate only if P2, malformed args typed failure (no throw). One probe per tool when schema incomplete.

Step 6 — Planning

Plan decoupled from execution. Validate plan before run. Optional parallel plans + judge. Optional Reflection (separate critique call; skip unless quality gate pays). Agent reports parameter values. references/planning-and-memory.md.

Step 7 — Memory

Internal weights vs context window vs episodic vs semantic external. Retention liability; no long-term memory valid. What goes where. references/planning-and-memory.md.

Before close Agent path: reality-test gate (five checks) in references/planning-and-memory.md.

Step 8 — Agent evaluation

Planning failures vs tool failures. Metrics: valid plan %, steps, cost, latency vs baseline. references/agent-evaluation.md.

Step 9 — Guardrails + Observability

Input/output guardrails. MTTD/MTTR mindset. Log enough to diagnose. Lock.

Step 10 — Close (two phases)

Locked: objective/I/O, Evaluation, failure diagnosis, adaptation path, (if Agent: tools, Planning, Memory, agent eval, Guardrails/Observability).

1. Announce: shared understanding. Interview complete.
2. Phase 1 (chat): ~150–200 words. Adaptation path, agent vs non-agent, top risk, MVP. Decisive.
3. Phase 2 (file): living design docs/specs/agent-design.md. Create docs/specs/ if missing. Canonical path. Do not ask. Missing: create full report. Exists: update current-state sections; append Changelog + this Interview Record session. Never blind-replace. Schema: references/report-template.md.

Standalone (no project FS): full report in chat. Tell user save as docs/specs/agent-design.md.

File = design handoff. Self-contained. Not agent-architecture.md (ns-agent-architecture).

Critical rules

• No Agent before Evaluation + failure diagnosis + ladder gates locked
• No framework, language, or implementation code
• Living design only docs/specs/agent-design.md — not docs/specs/agent-architecture.md
• One language: human opening. Doctrine labels English
• Not product Clarify — vague product scope → ns-spec-driven first
• Not implementation — never this skill
• No tool lock without typed schema checklist (references/tool-schema-design.md) — includes malformed-arg typed failure, no throw to caller

Reference map

Handoffs

Do not design ontology, extractors, answer-shape routing, or cite-or-refuse here — that is ns-graphrag. Do not invent DDL/hop SQL here — that is ns-postgres-rag.

Related skills (optional — when installed)

• ns-agent-architecture — after conceptual design locked (agent-design.md)
• ns-postgres-rag — Postgres retrieval design when RAG gate locks information path
• ns-graphrag — GraphRAG process (ontology, extract, answer shapes, cite-or-refuse) after retrieval mode is relational GraphRAG
• ns-spec-driven — Clarify if product scope vague
• ns-langgraph-agents — runtime only after architecture ADR; never from this skill directly