Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat: add optional high-level technical design to plan-beta skills#322

Merged
tmchow merged 1 commit into
mainfrom
feat/plan-pseudocode-guidance
Mar 20, 2026
Merged

feat: add optional high-level technical design to plan-beta skills#322
tmchow merged 1 commit into
mainfrom
feat/plan-pseudocode-guidance

Conversation

@tmchow
Copy link
Copy Markdown
Collaborator

@tmchow tmchow commented Mar 20, 2026

Summary

Technical plans are often valuable when they include pseudo-code, DSL grammars, or architectural diagrams in plans to validate the approach direction — without the plan crossing into prescriptive implementation code that downstream implementing agents take as gospel.

This PR adds optional "High-Level Technical Design" support at two levels:

  • Overview level (new plan section before Implementation Units): system-level shape — architecture diagrams, DSL grammars, state machines, data flow sketches. The skill chooses the right medium based on what the work actually involves.
  • Unit level (new optional field per implementation unit): tactical shape of a specific component, only when prose alone would leave the approach ambiguous.

Both levels carry explicit non-prescriptive framing: "This is directional guidance for review, not implementation specification."

Ultimately this paves a nice path to promote this to stable sometime soon.

Why this matters

There's a gap between "decisions, not code" (current plan-beta) and literal implementation code. Pseudo-code/DSL sketches sit in that gap — they let a reviewer say "yes, this direction is right" without dictating what the implementing agent should produce. The key concern driving the design: avoid specific code that the next implementation agent takes as gospel and reproduces verbatim.

Changes

ce-plan-beta:

  • Soften core principle to allow pseudo-code/DSL sketches with non-prescriptive framing
  • New Phase 3.4 with decision table for choosing the right medium
  • Optional per-unit "Technical design" field
  • Template updated with optional section and framing
  • Standard/Deep depth guidance clarified: optional sections should be omitted when they add no value

deepen-plan-beta:

  • Confidence gap checklists for technical design (when present and when absent)
  • Agent mapping for validating/strengthening technical design sections
  • Guardrails explicitly permit pseudo-code in both top-level and per-unit locations

…epen-plan-beta

User feedback indicated that seeing pseudo-code, DSL grammars, or
architectural diagrams in plans helps reviewers validate the approach
direction — without crossing into prescriptive implementation code that
downstream agents take as gospel.

Changes to ce-plan-beta:
- Soften "decisions, not code" principle to allow pseudo-code/DSL sketches
  framed as directional guidance
- Add Phase 3.4 "High-Level Technical Design" with a decision table for
  choosing the right medium (pseudo-code, mermaid, data flow, state diagram)
- Add optional per-unit "Technical design" field for unit-level sketches
- Update template with the new optional section and non-prescriptive framing
- Clarify Standard/Deep depth guidance that optional sections should be
  omitted when they add no value

Changes to deepen-plan-beta:
- Add confidence gap checklists for technical design (when present and absent)
- Add agent mapping for validating/strengthening technical design sections
- Expand allowed changes to cover both top-level and per-unit technical design
- Align guardrails to explicitly permit pseudo-code in both locations
@tmchow tmchow merged commit 3ba4935 into main Mar 20, 2026
2 checks passed
@github-actions github-actions Bot mentioned this pull request Mar 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant