analyze-stock-kpi: Instructions file for Codex

Agent Instructions for analyze-stock-kpi

Behavioural rules for AI agents working on this library-based stock KPI CLI. Shared dev workflow lives in CONTRIBUTING.md (test conventions, commit + PR conventions, branch protection, GHA workflow rules, changelog fragments, release flow); this document carries only what's agent-specific. For project overview see README.md; for module map + data flow see docs/architecture.md.

Core Rules

• Follow KISS, DRY, YAGNI, AHA — simplest solution that works, no speculative features, no premature abstractions
• Never assume missing context — ask if uncertain about requirements
• Never hallucinate libraries — only use packages verified in pyproject.toml
• Always confirm file paths exist before referencing in code or tests
• Never delete existing code unless explicitly instructed
• Touch only task-related code — bug fixes don't need surrounding cleanup
• Strict pydantic — every structured payload is a BaseModel; CLI / env via BaseSettings(cli_parse_args=True). No TypedDict, no dataclass.

Decision Framework

Priority order: User instructions → AGENTS.md → CONTRIBUTING.md → README.md → existing code patterns

Information sources:

• Requirements: task description (primary)
• Run / lint / test commands: make help
• Project version: src/__version__.py
• Library API shapes (yfinance, pydantic, etc.): context7 MCP, not training data

Anti-scope-creep: Implement only what is explicitly requested. Prefer landing small working slices over comprehensive rewrites within a single PR.

Quality Thresholds

Before starting any task, gut-check four dimensions on a 1 / 0 / -1 scale — the assessment exists only to pick the next action, so it has three states, not ten.

• Context — requirements, codebase patterns, and target API understood
• Clarity — implementation path and expected outcome are clear
• Alignment — follows project patterns + KISS / DRY / YAGNI / AHA
• Success — confident the task can be completed correctly