From 1fd3061369a8f111a5d7d51ac227798de7da34ea Mon Sep 17 00:00:00 2001
From: flash555588 <flash555588@users.noreply.github.com>
Date: Mon, 15 Jun 2026 17:05:54 +0800
Subject: [PATCH] docs(P2): add TODO/debt conventions and mark known debt

---
 AGENTS.md                   | 4 ++++
 CLAUDE.md                   | 3 +++
 src/main.ts                 | 1 +
 src/render/babylon/scene.ts | 2 ++
 src/render/three/scene.ts   | 2 ++
 src/settings.ts             | 2 ++
 src/view/direct-view.ts     | 2 ++
 7 files changed, 16 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index aa7e544..df1c454 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -80,6 +80,10 @@ For a custom browser, set `PLAYWRIGHT_CHROMIUM_EXECUTABLE`.
 - Do not copy GPL code. See `docs/mit-upstream-guidelines.md`.
 - Never paste or preserve PATs/tokens. See `SECURITY.md`.
 - If you change generated docs or behavior, update `CHANGELOG.md`.
+- Mark intentional shortcuts and known debt with `TODO(P<n>): <message>` or
+  `TODO: <message> (debt: <area>)`. Use `P0` only for urgent safety/correctness
+  follow-ups, `P1` for reliability/performance debt, and `P2` for maintainability
+  debt. Prefer `// TODO` comments for code and `<!-- TODO -->` for Markdown.
 
 ## Important Specs
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 2d70818..86ca01a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -59,4 +59,7 @@ mapping and `README.md` for longer verification notes.
 - Do not reset or discard existing changes unless explicitly asked.
 - Keep edits focused and update `CHANGELOG.md` for release-facing behavior.
 - Never paste or preserve tokens. Follow `SECURITY.md`.
+- Mark known technical debt with `TODO(P<n>): <message>` or
+  `TODO: <message> (debt: <area>)`. Use priorities `P0/P1/P2` to match the
+  severity convention in `AGENTS.md`.
 
diff --git a/src/main.ts b/src/main.ts
index 6418a75..2920480 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -129,6 +129,7 @@ export default class AI3DModelWorkbench extends Plugin {
     // Views are cleaned up by Obsidian calling onClose()
   }
 
+  // TODO(P2): extract into src/view/heading-pin-observer.ts and unit-test the selector/event wiring (debt: view-layer).
   private setupHeadingPinObserver(): void {
     const markdownContainerSelector = ".markdown-preview-view, .markdown-source-view";
     const headingSelector = [
diff --git a/src/render/babylon/scene.ts b/src/render/babylon/scene.ts
index 2c0aff4..d8d015a 100644
--- a/src/render/babylon/scene.ts
+++ b/src/render/babylon/scene.ts
@@ -229,6 +229,8 @@ function buildObjTextureCandidates(modelDir: string, rawPath: string, modelPath:
   return candidates;
 }
 
+// TODO(P2): split this class into loader/camera/light/annotation helpers.
+// Scene class is >1,700 lines and mixes rendering, interaction, and fallback logic (debt: renderer-babylon).
 export class BabylonModelPreview implements WorkbenchPreview {
   private static readonly annotationIdentity = Matrix.Identity();
   private static readonly annotationWorldPoint = Vector3.Zero();
diff --git a/src/render/three/scene.ts b/src/render/three/scene.ts
index 0162e1c..5acb61b 100644
--- a/src/render/three/scene.ts
+++ b/src/render/three/scene.ts
@@ -200,6 +200,8 @@ function getObjectPreviewBounds(object: Object3D) {
   );
 }
 
+// TODO(P2): decompose this class into loader/camera/light/annotation modules.
+// Scene class is >2,000 lines and mixes rendering, interaction, and knowledge capture (debt: renderer-three).
 export class ThreeModelPreview implements WorkbenchPreview {
   private readonly renderer: WebGLRenderer;
   private readonly scene: Scene;
diff --git a/src/settings.ts b/src/settings.ts
index 608ba6e..8c652c5 100644
--- a/src/settings.ts
+++ b/src/settings.ts
@@ -13,6 +13,8 @@ import { getRuntimeProcess } from "./utils/node-shim";
 
 const proc = getRuntimeProcess();
 
+// TODO(P2): split display() into section-builder methods; currently >500 lines (debt: settings-ui).
+
 function getConverterCommandPlaceholders(): {
   python: string;
   freecad: string;
diff --git a/src/view/direct-view.ts b/src/view/direct-view.ts
index 754c30e..ba3be7f 100644
--- a/src/view/direct-view.ts
+++ b/src/view/direct-view.ts
@@ -26,6 +26,8 @@ export const DIRECT_VIEW_TYPE = "ai3d-direct-view";
 const log = createLogger("direct-view");
 const THREE_WORKBENCH_DIRECT_EXTS = new Set(["glb", "gltf"]);
 
+// TODO(P2): migrate direct setState calls into typed PluginStore actions (debt: store-api).
+
 function createDefaultProfile(): ModelAssetProfile {
   return { tags: [], notes: "", annotations: [], createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() };
 }