@coldtea/pr-lens-agent-skill 0.1.2 → 0.1.3

package/SKILL.md

@@ -45,6 +45,14 @@ If you would rather not author the document yourself, `npx @coldtea/pr-lens-cli
 - **Attach file refs**: they become the permalinks a reviewer clicks.
 - **There is no findings lens.** PR Lens is the comprehension layer, not another review bot. There is no field for a bug, a risk or a security note, and a document that invents one is rejected rather than trimmed.
 
+## Choosing architecture views
+
+Treat architecture views as a C4-inspired decision tree, not a checklist. One useful view is enough for a small change. Start with system context when the change affects a user, an external system or a system boundary. Use a container view for the affected applications, services, jobs, data stores and runtimes. Add a component child only when an affected container's internals matter. Do not add code-level views by default.
+
+Every child moves down one level and covers a materially narrower scope. Skip empty, repetitive or speculative levels, and do not infer architecture from folder names alone. Two views should not carry substantially the same nodes and edges. Keep the unchanged direct neighbours that explain blast radius.
+
+Keep data-flow views as separate roots rather than nesting them in the architecture tree. Set `defaultOpen: true` on the highest useful architecture view. Lower levels should normally keep the default, `false`.
+
 ## What the validator will catch
 
 Read `references/graph-document.md` before writing. The four failures that account for nearly everything:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldtea/pr-lens-agent-skill",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "The PR Lens skill for coding agents: author a graph document from a diff, validate it, render it, and correct a repository's map.",
   "license": "MIT",
   "author": "Coldtea AI",

package/references/graph-document.md

@@ -141,6 +141,69 @@ The drill-down tree in the comment: up to 32 at the root, nesting up to 32 child
 
 `scope` is either `{ "kind": "all" }` (the default) or a selection naming at least one lane, node, edge or flow. The two are distinct states on purpose: removing the last element a view pointed at can never quietly turn it into a view of everything. A view's `lens` must be one the document declares.
 
+### Choosing architecture views
+
+Treat the architecture tree as a set of decisions, not a quota:
+
+1. Ask whether the change affects a user, an external system or a system boundary. If it does, start with a system-context view. If it does not, leave that level out.
+2. Show affected applications, services, jobs, data stores and runtimes in a container view. Make it the root when there is no useful context view; otherwise make it a child of that context.
+3. Add a component child only when the internals of an affected container matter to the change. Components may be modules, routes or functions, but the view should explain their responsibilities and relationships rather than mirror folders.
+4. Stop at components unless someone explicitly asks for code-level detail.
+
+One architecture view may be the right answer for a small change. Each child must move down exactly one level and cover a materially narrower scope. Skip a level when it would be empty, speculative or a repeat of its parent. Do not create two views with substantially the same nodes and edges, and do not infer a boundary from a folder name alone. Keep unchanged direct neighbours when they make the blast radius clear.
+
+Set `defaultOpen: true` on the highest useful architecture view. Lower levels should normally stay collapsed. A data-flow view describes an ordered sequence, so keep it as a separate root instead of placing it inside the architecture hierarchy.
+
+This compact fragment shows the shape. The selected ids refer to elements declared elsewhere in the document:
+
+```json
+{
+  "views": [
+    {
+      "id": "checkout-context",
+      "title": "Checkout in its environment",
+      "lens": "architecture",
+      "defaultOpen": true,
+      "scope": {
+        "kind": "selection",
+        "nodes": ["shopper", "commerce-platform", "payment-provider", "fulfilment-system"],
+        "edges": ["shopper-to-commerce", "commerce-to-payment", "commerce-to-fulfilment"]
+      },
+      "children": [
+        {
+          "id": "checkout-containers",
+          "title": "Checkout containers",
+          "lens": "architecture",
+          "scope": {
+            "kind": "selection",
+            "nodes": ["storefront", "checkout-api", "orders-db", "payment-provider"],
+            "edges": ["storefront-to-checkout", "checkout-to-orders", "checkout-to-payment"]
+          },
+          "children": [
+            {
+              "id": "checkout-components",
+              "title": "Checkout API components",
+              "lens": "architecture",
+              "scope": {
+                "kind": "selection",
+                "nodes": ["checkout-route", "order-service", "payment-client"],
+                "edges": ["route-to-orders", "orders-to-payment-client"]
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "place-order-flow",
+      "title": "Placing an order",
+      "lens": "data-flow",
+      "scope": { "kind": "selection", "flows": ["place-order"] }
+    }
+  ]
+}
+```
+
 ## Layout
 
 ```json