Summary
The runtime enforces RESEARCH as mandatory before Actor, but the hook hint says research-agent is conditional for 3+ existing files or high risk. This contradiction can cause agents to skip research and hit a hard orchestrator stop, wasting turns.
Paper basis
FastContext is explicitly optional at the main-agent level: use it for cold-start repository exploration, broad cross-file localization, or failed direct search; skip it when the file/symbol is already known. MAP currently enforces a research artifact, but not necessarily an external subagent call. The wording should distinguish mandatory persisted research from conditional delegated research-agent use.
Current evidence
- src/mapify_cli/templates_src/map/scripts/map_orchestrator.py.jinja:1335-1351 enforces that .map//research/<subtask_id>__*.md exists before validate_step 2.2 passes.
- src/mapify_cli/templates_src/skills/map-efficient/SKILL.md.jinja:239-258 labels Phase RESEARCH 2.2 as Required and tells users to call research-agent then save_research.
- src/mapify_cli/templates_src/hooks/workflow-context-injector.py.jinja:340-348 says Run research-agent (conditional: 3+ existing files or high risk).
- src/mapify_cli/templates_src/codex/skills/map-efficient/SKILL.md.jinja:160-169 says use researcher when independent exploration is useful; otherwise research in current session, then save_research.
Proposal
Make the policy explicit:
- mandatory: a persisted research artifact before Actor
- conditional: whether that artifact must come from research-agent/researcher versus direct narrow research in the current session
- skip/no-op: only through the documented no-op subtask short-circuit when the subtask does not need Actor/Monitor
Acceptance criteria
- Hook hint, /map-efficient, Codex $map-efficient, and orchestrator error message use consistent terminology.
- validate_step 2.2 error tells the user whether to run research-agent or save direct findings.
- Tests assert that shipped template wording does not contain contradictory mandatory/conditional wording.
- Docs include a small decision table: known single file, cold-start multi-file, greenfield/new file, docs-only/no-op.
Summary
The runtime enforces RESEARCH as mandatory before Actor, but the hook hint says research-agent is conditional for 3+ existing files or high risk. This contradiction can cause agents to skip research and hit a hard orchestrator stop, wasting turns.
Paper basis
FastContext is explicitly optional at the main-agent level: use it for cold-start repository exploration, broad cross-file localization, or failed direct search; skip it when the file/symbol is already known. MAP currently enforces a research artifact, but not necessarily an external subagent call. The wording should distinguish mandatory persisted research from conditional delegated research-agent use.
Current evidence
Proposal
Make the policy explicit:
Acceptance criteria