update docs

[Mike Tokic (mitokic)]

This pull request enhances the documentation and guidance for R package development, with a strong emphasis on function documentation, model selection policy, and code review practices. It introduces a comprehensive section on model selection ownership and workflow, updates rules to require documentation for all functions (including internal helpers), and clarifies the expectations for code reviewers. Several inline code comments are also improved for clarity.

Documentation and Policy Updates

• .claude/rules/r-package.md: Adds a new section requiring documentation for every function, including internal and helper functions, with clear guidance on scope, style, and update practices.
• AGENTS.md, CLAUDE.md: Updates references and instructions to require documentation for all functions, explains where to find model selection guidance, and adds reminders to follow the function documentation contract for every new or modified function. [1] [2] [3] [4]

Model Selection Guidance

• .github/agent-guides/architecture-map.md: Adds a detailed "Model Selection" section mapping selection decisions to their owner functions and files, explaining the selection process, key concepts, and tests to consult. This clarifies boundaries and responsibilities for selection logic.
• .github/agent-guides/evaluation-cases.md: Adds a testable case for changes to internal functions in R/forecast_selection.R, specifying documentation and policy preservation requirements.

Code Comments and Internal Documentation

• R/agent_iterate_forecast.R: Improves inline comments for functions related to selection metrics and logging, clarifying the rationale, expected behavior, and contract for these internal helpers. [1] [2] [3] [4]

These changes collectively raise the standard for internal documentation, clarify model selection ownership, and provide more actionable guidance for both development and review.

[Copilot]

🟡 Changes recommended

The test-helper rule is not activated for test paths, and some selection guidance is internally inconsistent.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR strengthens developer guidance for function documentation and model-selection maintenance.

Changes:

• Defines documentation requirements for all functions.
• Adds a model-selection architecture map and vignette guidance.
• Clarifies selection, update, and persistence logic with inline comments.

File summaries

File	Description
.claude/rules/r-package.md	Defines function-documentation contracts.
.github/agent-guides/architecture-map.md	Maps model-selection ownership and tests.
.github/agent-guides/evaluation-cases.md	Adds a selection-helper guidance case.
AGENTS.md	Updates repository-wide development guidance.
CLAUDE.md	References the expanded package rules.
R/agent_iterate_forecast.R	Clarifies metric and promotion behavior.
R/agent_update_forecast.R	Clarifies update acceptance behavior.
R/final_models.R	Clarifies selection and averaging behavior.
R/forecast_selection.R	Documents selection-policy internals.
vignettes/best-model-selection.Rmd	Expands the model-selection walkthrough.

Review details

• Files reviewed: 10/10 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.