n3Plugins Decision Playbook

Compact checklists for recurring task patterns. Derived from git history and repeated agent work. Read the relevant pattern before starting implementation.

---

Walker / Transport Changes

Triggered by: transport enum changes, collision map updates, Shortest Path resource updates, route handler modifications.

1. Run focused transport tests first:

   .\gradlew.bat test --tests com.n3plugins.sdk.walker.PluginTransportActionResolverTest --tests com.n3plugins.sdk.walker.NpcWalkerActionTest --tests com.n3plugins.sdk.walker.CanoeWalkerActionTest --console plain

2. Run auditWalkerTopology to verify transport topology:

   .\gradlew.bat auditWalkerTopology --console plain

3. If Shortest Path resources changed, verify pinned resource integrity:

   .\gradlew.bat test --tests com.n3plugins.sdk.walker.* --console plain

4. Run full walker suite, then broader tests.
5. Live verify: path overlays, transport row execution, gangplank recovery, and failed crossing replanning.

---

Revision Mapping Updates

Triggered by: RuneLite version bump, OSRS revision change, packet/reflection mapping drift.

1. Update revision-mappings/rev<N>.properties with evidence from ASM analysis.
2. Update N3PLUGINS_SOURCE_OF_TRUTH.md revision and RuneLite version.
3. Run revision health check tests:

   .\gradlew.bat test --tests com.n3plugins.PacketUtils.* --console plain

4. If menu-action dispatch changed, clear ~/.runelite/cache/menu-action-plan.json and verify cold-cache resolution.
5. Verify revision-evidence cache at ~/.runelite/cache/revision-evidence-<N>.json.
6. Live verify: bootstrap ready state, native menu resolution, packet sends.

---

Plugin Porting (from External Source)

Triggered by: adapting Microbot, PiggyPlugins, or other external plugin code into n3Plugins.

1. Domain review: verify OSRS mechanics, account requirements, UI assumptions.
2. Map external APIs to n3 equivalents:
   • External Rs2Bank → BankActions
   • External Rs2Npc → NPCActions
   • External Rs2Widget → Widgets / sdk.widgets
   • External sleep/sleepUntil → remove; use tick-driven re-evaluation
3. Replace polling loops with event-driven onGameTick state checks.
4. Add Break Handler integration (register at startup, track active work only).
5. Register in runelite-plugin.properties.
6. Update SOT registered plugins table.
7. Write tests: controller, workflow, state machine (deterministic, no live client).
8. Review: safety, anti-detection shape, pacing, shared API usage.

---

SDK Refactors (Rename / Restructure)

Triggered by: API rename, package reorganization, shared helper consolidation.

1. Use Serena rename_symbol or find_referencing_symbols when available.
2. Consumer sweep: find all callers of the changed surface.
3. Update all test files referencing the old names.
4. Update SOT if package maps or action catalog changed.
5. Regenerate agent MCP SDK index:

   .\gradlew.bat generateAgentMcpSdkIndex --console plain

6. Run full test suite — SDK changes can break any consumer.
7. Run checkDocDrift to catch documentation references to old names.

---

Test Repair (After Behavioral Changes)

Triggered by: test failures after a feature or SDK change.

Priority order:

1. Contract tests — ApiJavadocCoverageTest, LegacyConstantParityTest, packaging tests
2. Scenario tests — sdk.events.scenario, sdk.events.fixture infrastructure
3. Focused plugin tests — tests in the changed plugin's package
4. Broad regression — .\gradlew.bat test --console plain

Fix the root behavioral issue, not the test assertion. If the same test fails 3 times, stop and document the evidence.

---

Documentation Changes

Triggered by: modifying docs/**/*.md, skills, AGENTS.md, or SOT.

1. Run the frontmatter fixer on changed docs:

   python scripts/fix-docs-frontmatter.py <changed-paths>

2. Run documentation audits:

   .\gradlew.bat auditDocs checkDocDrift --console plain

3. Regenerate LLM context:

   python scripts/generate_llm_docs.py
   python scripts/generate_llm_docs.py --check

4. If canonical pages were added, register in docs-site/sidebars.js.

---

Failure Taxonomy

Quick lookup for common failures. From docs/agent-testing-loop.md.

Failure	Likely Cause	Next Step
Compile error	Signature drift, import mismatch, Java 11 violation	Read the live source, fix the smallest mismatch
Mockito setup failure	Inline/static mocking, mock inside thenReturn(...), final class	Refactor to injected collaborators or assign mocks to locals first
Widget miss	Hidden widget, wrong group/child, text tag mismatch, revision drift	Use WidgetExplorer, require visibility, compare against live UI
Pacing stall	Driver consumes ActionPacer, missing recordAction, double tick owner	Check PacketUtilsPlugin ownership and action-layer pacing
Walker stall	Plugin owns walker tick, stale route, missing transport, unreachable target	Inspect WalkerPath status and shared walker docs
Packet/runtime mismatch	Client revision or obfuscated mapping drift	Run revision health checks and verify in-client
Docs mismatch	SOT or source changed after prose written	Re-read source and update docs/catalog together