project-tech-design
Use when writing or revising a technical design that settles an architecture, an entity model, a module boundary or a subsystem, or when a review comment reopens such a decision.
- License 许可
- AGPL-3.0
- 所属仓库
- loupe-ac/loupe
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- project-tech-design
- description
- Use when writing or revising a technical design that settles an architecture, an entity model, a module boundary or a subsystem, or when a review comment reopens such a decision.
03 SKILL.md 正文
Technical designs
A technical design settles an architecture. An implementation plan settles tasks. Write the design first.
Send every design to the Loupe app for review. Invoke loupe-documents before you write. That skill gives the format rules for the review UI. This skill gives the content rules.
Follow plugins/loupe-lifecycle/skills/loupe-stage-tech-design/references/tech-document.md for the design sections, the recommendations and the estimate marks. This skill adds the rules that belong to this project.
Write the design for a reader who knows the product. The section "Write for a reader who knows the product" of loupe-documents references/design-structure.md gives the rule.
Write the document in ASD-STE100 Simplified Technical English. The writing rules are in compressing-skills.
An ADR name such as 0001-app-over-worker never gets a tooltip on the review page. Give it a meaning inline at its first mention in each section. loupe-documents rule 16 says the same for an outside ID.
Verify each claim against the code
Read the code before you state a fact about it. Never write a count from memory.
One audit design stated five wrong numbers. It claimed 11 security call sites, and the code had 14. It claimed 22 silent handlers, and the code had 27. It claimed one privacy violation, and the code had 26. It also described a renaming workstream that did not exist, because every operation name was already correct.
Run the search. Count the result. Put the number in the document.
Say what you could not verify. Silence reads as confidence.
A claim about a library, an API, a database or speed needs proof too. Read the current docs, or run a proof of concept, as "Facts and recommendations" of the stage skill says.
Separate the trigger from the problem
The trigger is the event that made you look. The problem is what the code gets wrong.
A lapsed trial blocked an agent. That was the trigger. One status column cannot hold two facts. That was the problem.
Write both, and keep them apart. A design that fixes the trigger leaves the problem in place.
Make the change easy, then make the easy change
Kent Beck states the rule. Apply it when a small feature does not fit the model.
A comped account had to stack with a Stripe subscription. One status column could not express it. The correct design added subscription records first, and the comp then cost one row.
Difficulty is evidence. When a small change fights the model, the model is the work. Say so in the document, and plan the enabling change as its own step.
Cover the project's own checks
Give the document a section for the checks the work must satisfy. Gamache, arkitect, and the migration rules all constrain a design.
List the rules that apply, and say what each one forces. A design that ignores them produces a branch that cannot pass just ci.
Read the five gamache layers before you claim no rule applies. project-backend lists them in references/gamache.md.
Order the work around live data
A step that touches live data needs its own entry in the work order. Say what breaks if the migration is wrong.
Take the example case from this project
Take the case of each worked example from this project. A card of the board, a page of the dev seed or a rule of a skill are good cases.
Common mistakes
| Mistake | Correction |
|---|---|
| A count taken from memory | Run the search, then write the number |
| The trigger described as the problem | Write both, and keep them apart |
| "All 107 call sites" | Verify the scope; 45 of them were diagnostics |
| A decision fence with two paragraphs above the options | One paragraph converts, two do not |
| An implementation plan submitted as a design | Settle the architecture first |
| A decision written in class names | Write it for a reader who knows the product |
| "I recommend option 2", or "under D1 option 1", in a decision | Say what the option does, and state the fact inline (loupe-documents rule 18) |
04 同仓库更多 Skills
loupe-workers
Use when reading worker runs or bridges through the loupe MCP, stopping, resuming or holding workers, cancelling a bridge command, or recovering workers after a usage limit or network outage.
loupe-site-review
Use when acting on live-review feedback through the loupe MCP: reading the feedback of a card or project, fixing it, or marking it addressed.
loupe-inbox
Use when an agent needs a decision, answer or review from the project owner through the loupe MCP, hands a question or to-do to a person, resumes after an ask closed, or needs its session id.
loupe-documents
Use when writing or revising a document for the Loupe app through the loupe MCP, such as a plan, spec, RFC, audit report or retrospective.
loupe-discovery
Use when a bridge runs a discovery run of a Loupe project, when a prompt names loupe-discovery, or when writing a readiness report.
loupe-board
Use when working a Loupe project board through the loupe MCP: reading or writing a card, moving a card, changing the columns, or linking a document or a pull request to a card.