docs: add minimal requirement shaping guidance

2026-05-28 08:42:35 +00:00
parent 5ecff66f83
commit dc227f3e7d
2 changed files with 56 additions and 1 deletions
@@ -39,6 +39,61 @@ Before accepting a requirement, answer these questions:

 If the answers are weak, the requirement should be dropped, narrowed, or rewritten.

+## Minimal Requirement Shaping
+
+Before writing a long-term reference, implementation plan, issue, prompt, or task
+breakdown for a broad requirement, first compress the requirement to the smallest
+domain model that satisfies the current external need.
+
+Use an explicit simplification pass:
+
+1. List the rich or default architecture that first comes to mind.
+2. Remove roles, groups, projects, capabilities, services, middleware, gates, and
+   audit surfaces that are not needed for the first useful workflow.
+3. Produce a before/after table showing what was removed or merged.
+4. Ask whether the remaining model can be implemented with an existing service,
+   database, and control path before introducing a new microservice or middleware.
+5. Record postponed components as trigger-based follow-ups, not as phase-one
+   dependencies.
+
+For example, a multi-user hardware-lab requirement should first check whether
+`admin/user`, session ownership, and a single grant table are enough before
+adding group/project RBAC, capability matrices, OpenFGA, Keycloak, service mesh,
+or Kubernetes tenant abstractions. A middleware is justified only when a concrete
+trigger appears, such as external identity integration, inherited permissions,
+tenant self-service namespaces, or admission-policy enforcement that cannot be
+handled by the existing service boundary.
+
+## Reference And Plan Split
+
+When the simplified requirement needs documentation, split the output:
+
+- `docs/reference/*.md` owns stable design goals, authority boundaries, table or
+  API contracts, request paths, service ownership, and acceptance criteria.
+- `docs/plan/*.md`, GitHub issues, or project-specific planning docs own current
+  state, source observations, implementation order, migration steps, incompatible
+  changes, and open work.
+
+The reference must not become a process log. It should explain the target shape
+as if a future implementer has not seen the chat. The plan should explain how the
+current source differs from that target and what must change.
+
+For product or platform designs that touch multiple services, the plan should
+name each affected service and classify the change:
+
+- data/schema change;
+- API or request-chain change;
+- frontend behavior change;
+- worker/runtime behavior change;
+- deployment or namespace/data-plane change;
+- incompatible behavior that deliberately removes an old route, default, or
+  fallback.
+
+Do not preserve legacy compatibility just because it existed before. If the user
+has accepted a simplified target, old assertions, public routes, feature flags,
+fallbacks, or dual paths that conflict with the target should be removed in the
+same plan, with the user-facing breakage and migration handling stated clearly.
+
 ## Short-Term Work

 Short-term work is the work that improves the current usable system quickly.