ai-session-search: Skill for Codex

Maintain AI Session Search

Work from measured repository and installed-state evidence. Preserve the product contracts recorded in the maintainer requirements and design decisions. Read that document before changing public behavior, installation, configuration, provider parsing, budgets, capabilities, or release machinery.

When the task affects match evidence, typed skill capabilities, ownership lifecycle, updates, or installed dogfood, also read the applicable detailed requirement and tracked sources in the document's Verification map. If the checkout has a focused maintainer note for that topic, use it as supplemental historical evidence. Preserve verified mechanism comparisons, invariants, state taxonomy, deferrals, test matrices, and complexity analysis; do not replace them with this skill's summary.

Prioritized requirement catalog

Treat these identifiers as stable review anchors. The detailed rationale and verification map live in the maintainer requirements document. Catalog order expresses priority; the number preserves identity and does not determine priority.

P0 — discovery, architecture, correctness, and data safety

• REQ037-explore-before-change — Search the repository, prior sessions, docs, tests, history, and current installed state before judging or changing behavior.
• REQ038-map-semantic-ownership — Map the conceptual behavior, data flow, defaults, validation, ordering, lifecycle, and owners across every affected surface before designing a fix.
• REQ039-reuse-or-improve-architecture — Use the strongest existing seam and shared abstraction, improving it when evidence justifies the change instead of creating a parallel mechanism.
• REQ048-adopt-proven-libraries — Search manifests, lockfiles, imports, and existing abstractions before building infrastructure. Reuse a fitting dependency first; otherwise evaluate mature, widely used, actively maintained libraries for contract fit, lifecycle safety, security, MSRV/platform support, performance, dependency cost, and release risk. Adopt one only when it robustly removes more custom machinery than it adds; record the concrete gap when custom code remains.
• REQ040-eliminate-semantic-duplication — Search for duplicated meaning, not only repeated text; keep one authoritative implementation for each contract and thin surface adapters.
• REQ041-optimize-multi-objective-outcomes — Improve or preserve correctness, task success, usability, latency, throughput, memory, output size, cost, maintainability, and user time together.
• REQ044-automate-safe-problem-solving — When intent, authority, and a safe deterministic action are clear, solve the problem in the owning service; make typed correct use the easiest path and keep semantic choices explicit.
• REQ045-own-and-clean-resources — Give connections, snapshots, iterators, locks, subprocesses, buffers, and temporary artifacts one RAII owner; close without draining unread work on completion, break, drop, cancellation, error, broken pipe, and foreign-language exit paths.
• REQ046-preserve-boundary-results — Preserve values, nullability, identities, ordering, coordinate spaces, terminal states, errors, and ownership across Rust, PyO3, Python, CLI, MCP, and serialization boundaries.
• REQ047-return-actionable-recovery — When automatic safe completion is impossible, return the exact failed state, why automation stopped, what was preserved or cleaned up, the smallest next action, and a verification step.
• REQ010-protect-complexity-bounds — State and verify time, retained-memory, allocation, I/O, latency, concurrency, and output-growth bounds; protect them with representative benchmarks.
• REQ027-use-tdd — Reproduce the defect and add the smallest failing shared-layer test before implementation, then cover every affected adapter and installed surface.
• REQ042-plan-fine-grained-work — Keep a current dependency-ordered task plan with explicit evidence, verification, completion, deferral, and external-action states.
• REQ043-reread-active-plans-after-compaction — After context compaction or session resumption, reread every active plan sequentially from start to finish, then reconcile all work performed in the current session against its requirements, ordering, non-goals, tests, and completion gates before resuming edits. Targeted excerpts and summaries are not substitutes.
• REQ001-preserve-user-data — Never lose source sessions, indexes, configuration, edits, or unrelated work while installing, migrating, repairing, or uninstalling.
• REQ002-share-typed-contract — Route Rust, Python, CLI, and MCP through shared typed requests and responses; adapters translate syntax, not product semantics.
• REQ003-preserve-surface-semantics — Keep deliberate surface differences explicit: when no purpose or operation default applies, omitted literal/regex/queryless limits mean all results in Rust, Python, and CLI, while MCP supplies a finite context-safe page; fuzzy search is always finite.
• REQ004-separate-retrieval-presentation — Presentation windows and character budgets may shorten displayed values but never alter matching, rank, membership, context, or pagination.
• REQ005-return-match-evidence — Every queried hit exposes visible, match-centered evidence; literal mode also preserves the exact source occurrence and coordinates.
• REQ006-report-extent-honestly — Structured output states returned count, paging, ordering, presentation policy, completeness, and whether the selected field has text before or after each returned view so shortened output cannot look complete.
• REQ007-preserve-page-identity — Evidence, context, formatting, or presenter failures must not change offsets, next-page identity, or the selected result set.
• REQ008-reject-hidden-cutoffs — Do not add silent row, byte, content, or elapsed-time cutoffs; expose intentional bounds as named parameters with origins.
• REQ009-bound-fuzzy-search — Score the complete eligible fuzzy corpus while retaining a finite, deterministic top-K page; reject unbounded fuzzy requests.
• REQ011-validate-language-boundaries — Keep PyO3 conversions, Rust types, Python stubs, exceptions, nullability, enums, and serialized output lossless and aligned.
• REQ012-reject-invalid-combinations — Reject conflicting or unsatisfiable parameter sets with actionable errors instead of returning misleading empty or partial results.