[darko-mijic]

What this opens

This pull request opens the design work for the Protocol's human readings. The aim is the UX and information architecture of Studio views for particular delivery roles and kinds of work, built on one premise. All delivery state lives in one graph, so every view is a projection: free to regenerate, never a second store. That lets the product serve many readers without limiting itself to today's pages.

It is the first of many iterations, stacked on #41 (the article refresh that prepared this pass). It deliberately sets no visual style, because an existing UI library and design system will be introduced later. What lands is the foundation:

• the product record (PRODUCT.md);
• a design foundation of twelve documents under docs/design/;
• a change to how every session in this repository starts: eleven mandatory graph queries that replace the owner's TODO in AGENTS.md.

The session also produced something the owner expected: a large set of engineering improvements. When research agents explored this self-hosted repository, they mostly searched and read files instead of asking the graph, even though the handbook makes the graph mandatory. Mining their transcripts measured that gap and turned it into a ranked list of what the graph should answer up front. That list became the orientation queries. The frictions became considerations for the next engineering session.

A tour

Links are pinned to 760a88c5.

Surface	The idea	Start here
Product record	Users, purpose, positioning, constraints and principles for design work. Traditional delivery roles come first, with niche, specialised and AI-powered readings kept on the table.	PRODUCT.md
Working method	The graph first: load the reading skill, ask the graph, read a carrier last. Every design brief carries the queries that define its scope.	docs/design/README.md · 09 Design method
Roles and personas	Four tiers, from core delivery roles to ultra-specialised and non-human readers, framed by the RUP disciplines the Protocol maps as filters, never phases.	01 · 11 RUP roles and artifacts as projections
The seed design, mapped	What the pre-code design imagined for people, what became of each idea, and the opportunity it leaves.	02
Reading material and IA	What a reading can draw on (the reader's nine entry points, the recipes as demand evidence), how readings are composed, how people arrive, and object pages, task flows and role homes.	03 · 04
AI-powered readings	A ladder of AI roles ordered by how much determinism each keeps. Its strongest idea is that an agent authors the selection or the generator, and the graph supplies the content.	05
What the repository settles	Eight technical questions answered from the repository, each checked by an adversarial agent and against the graph, with what stays open for design.	08
Studio baseline	Today's Studio read page by page as a prototype, pinned to the preview it was read from.	10
Cycles and the long horizon	The cycle plan, the first briefs to shape, and the design questions that months of iteration will answer.	06
Hand-off to engineering	Graph needs, reader frictions and on-ramp observations. Design sessions record them; engineering sessions decide.	07
Analogous products	Developer portals, requirements and ALM tools, and AI spec-driven tools: where truth lives in each, and one lesson per product.	12
Orientation	A short "Orient before work" block in the handbook, with eleven queries and their reading notes in a file beside the reading skill.	AGENTS.md · orientation.md

What the research found

These are measurements of this session's research, not of the corpus. Over the 31 research-agent transcripts, agents made about 1,200 search and file-read calls, which returned about 5.9M characters, and 194 sdp:q calls, which returned about 0.38M. About 480 of the file calls (about 2.35M characters) read Spec carriers the graph already holds. The needs behind them ranked as follows:

1. what one or a few named Specs say;
2. where a concept lives;
3. whether a cited entry address resolves and what it says;
4. which code realizes a Spec;
5. reading a Pack or a family as one design.

Re-asked as shaped queries, each took one call and a fraction of the text. The eleven orientation queries answer these needs before work starts and show the correct answer paths in working bodies.

07 also records, each reproduced with a query:

• reader frictions: guessed answer shapes that fail silently, a missing reader method that does not name the real ones, two concept searches that disagree, unshaped answers that flood;
• on-ramp observations: the mandatory skill was skipped even when read; the skills are large single files without disclosed reference; the skills sit outside the graph; the "Next work" block's sdp validate removes the page roots; the green gate reads macOS .DS_Store files as projection drift.

Rulings

Rulings the owner made:

Ruling	One line	Carried in
Design sessions never edit graph inputs	Design records needs for engineering sessions to consider, and never edits carriers, Packs or anchors	07, PRODUCT.md
The graph first	Skill, then graph, then files; part of every piece of work is specified as graph queries	README, 09
Keep the option space	Personas and niche, specialised, ultra-specialised and AI-powered readings stay on the table; tier 1 is a focus, not a limit	01, 05
Technical product managers before product designers	Early cycles serve architecture-minded product roles; visual product designers are a later audience	PRODUCT.md
Open core, exploratory commercial Studio	The core stays open source and free; a desktop, web and CI/CD Studio is exploratory	PRODUCT.md, 04
No visual style yet	The existing UI library and design system arrive later and bind	PRODUCT.md
Orientation: short block plus disclosed file	The handbook carries a short block; the eleven bodies live beside the reading skill	AGENTS.md, orientation.md
The skills get fixed next	The owner's direction for the very next session: progressive disclosure for the skills, and a better pitch for sdp:q as a complement to an agent's own tools	07

Rulings delegated to the agent, awaiting the owner's review:

Ruling	One line	Carried in
"Persona" as a design-material word	The job stories bind to no persona, so personas live in design material only and are paired with job stories	README, 01
Provisional design terms	Reading, role home, object page, basis line and the other coinages stay provisional until the owner rules them	README
"Readiness author / question decider" for the owner role	A Spec names no owner, so the persona is named after the act, not after ownership	01
A corpus home for the design project, as a proposal	A design Pack with idea captures was recommended by the research critic, but it stays a proposal under the owner's rule	07
The orientation file stays out of the package	package.json lists each SKILL.md only; shipping an adopter-neutral form is left to engineering	07

No registry row is added; docs/concept/DECISIONS.md is unchanged.

What no human view shows yet

No projection changes in this pull request. The Studio, Design Review, census, Mermaid, Gherkin and the vault render exactly as at the base. The design foundation is Markdown for now; the first readings it proposes reach prototypes in later iterations.

Try it

From a checkout of design/foundation-1:

npm ci
# The handbook's new opening: run the eleven orientation queries in order.
python3 - <<'EOF'
import re, subprocess
text = open(".agents/skills/sdp-agent-surface/orientation.md").read()
for n, cmd in enumerate(re.findall(r"```bash\n(.*?)\n```", text, re.S), 1):
    print(f"--- query {n}", flush=True)
    subprocess.run(cmd, shell=True, executable="/bin/bash")
EOF

At the head, all eleven exit 0 and print about 21K characters in total.

Feedback wanted

• The orientation list. Does it answer what you need before work, and is "Orient before work" placed and worded so agents actually run it?
• The reading model in 04. Do the parts of a reading, the arrival table, and object pages plus role homes hold up as the backbone for role-specific Studio views?
• The AI ladder in 05. Is "the agent authors the selection or the generator; the graph supplies the content" the right direction for specialised and AI-powered readings?
• The engineering hand-off in 07. Which reader frictions and on-ramp observations should the next engineering session take first?
• The delegated rulings above.

The next work, from the roadmap

Roadmap: The Protocol's roadmap pack:roadmap

To state means the floor allows ready and a person still judges the statement. Built means every Spec of the entry's work states ready and has an implementation binding; it reports no passing test and no deployment.

The Protocol's next work, first entry first. The order is a preference: it dates, gates and sequences nothing, and what each entry still needs is read from the graph each time.

First the cleanup that removes the frozen plans, review reports and superseded concept material, as the roadmap and the pull request record make possible. Then the two steps a reader of the Studio's pages could not take, the words of a test line that checks a declaration and an outside register's entries, and then the composed-intent model the build backlog holds. What the first adopter's mass update asks for joins when the owner selects it; a capture landing adds nothing here. An entry leaves by an edit to this manifest once its selected work is complete or no longer belongs among the next work.

To design

Place	Entry	Next	Purpose and reach
1	The Protocol removes its frozen plans, review reports and superseded concept material spec:protocol.delivery-record-cleanup	itself idea → scoped, nothing holds it; blocked by spec:protocol.delivery-record-cleanup#question.durableContent	Remove plans/, reviews/ and the superseded concept material from the tree, after moving into the graph the durable content they still hold, so the repository keeps one delivery record: the graph, git and the pull requests.
3	An outside register is a named Studio input, so a cited token links to its entry spec:consumers.spec-studio.register-input	itself scoped → defined, held by no-blocking-open-questions; blocked by spec:consumers.spec-studio.register-input#question.registerEntry, spec:consumers.spec-studio.register-input#question.inputForm	A cited token reads as bare text on every page, and the register that defines it is neither linked nor shown.

To state

Place	Entry	Earlier waiting statements	Purpose and reach
2	A pinned declaration shows the words of each test line that cites it spec:consumers.spec-studio.cited-line-text	No preceding waiting statement in the statement queue.	The declarations page names each citing line by file and line only, so the reader leaves the page to read it, and has no route at all when the page set carries no source link.

To build

Place	Entry	Purpose and reach	Rests on
4	Views compose scoped intent instead of patching canonical source spec:consumers.edit-model	Let a view frame a requested change without giving derived surfaces a direct write path to canonical source.	nothing unbuilt

Waiting on the owner

• spec:protocol.delivery-record-cleanup#question.durableContent (blocking), place 1: Which content in plans/, reviews/ and the concept documents does no Spec, test, decision or recipe carry yet, and where does each piece belong?
• State spec:consumers.spec-studio.cited-line-text: it states scoped and its floor allows ready; place 2
• State spec:protocol.delivery-record-cleanup: it states idea and its floor allows scoped; place 1

Deferred, with their triggers

• spec:carrier.sdp-import.feature-adapter#question.featureAdapter: Which bare .feature constructs can an import adapter preserve honestly? Trigger: an adopter migrates a gen-1 .feature corpus into the Protocol
• spec:consumers.agent-surface.combination-coverage#question.combinationCoverage: Which combinations of slot values should coverage enumerate and report? Trigger: a design pass asks which combinations no example exercises
• spec:consumers.ai-assisted-reading#question.aiPresentationBoundary: If an assistant generates explanations or arrangements beyond selecting deterministic readings, what contract keeps its output distinct from graph claims and makes the exact reading reviewable, including how the exact output is retained with its model, prompt and inputs? Trigger: the UX design pass measures that assistant selection or a generated explanation helps a named review task
• spec:consumers.impact-graph.symbol-reach#question.symbolIdentity: Which language-neutral identity and extraction boundary can support exhaustive symbol reach without freezing a single compiler's representation into the Protocol? Trigger: a reader needs symbol-level reach that file-level imports and curated anchors cannot give
• spec:consumers.projections-model.roadmap-views#question.releaseReader: Does a reader need release or baseline views that the roadmap, the recipes and git tags do not serve? Trigger: the first published release
• spec:consumers.reference-projection#question.namedOutsideReader: Does a human reader outside the repository need a reference projection the four shipped roots do not serve? The taxonomy row is not that reader. Trigger: a named consumer outside the repository, with a way to measure that demand inside the arc that builds the projection
• spec:consumers.structural-mermaid#question.namedStructuralReader: Does a reader need diagrams rooted at code units, which census tables and Spec-rooted one-hop Mermaid do not serve? Trigger: a named reader with that need, plus a decision that refines spec:decisions.shipped-projections-frozen for the affected Mermaid rendering or supersedes that ruling whole
• spec:observation.run-evidence.bound-file-freshness#question.freshness: When should changes to bound files make recorded run evidence stale? Trigger: a reader cannot tell whether a run at another commit still applies, because nothing says whether its bound files changed since
• spec:observation.runtime-overlay#question.observationIdentity: Which external observation identity and freshness boundary is small enough for the graph while still supporting an honest observed delivery fact? Trigger: An adopter needs runtime measurements linked to measurable Spec targets and can supply an observation identity and freshness policy for review.

This pull request adds no roadmap entry; entries join or move only on the owner's word. The owner's direction for the very next session sits outside the roadmap: fix the skills (progressive disclosure), better promote sdp:q, and start working through the hand-off in 07.

Record

• Stack: base docs/articles-refresh-1 (docs(articles): re-pin the series to f990bded for the first design pass #41), at 53804437. GitHub retargets this pull request when docs(articles): re-pin the series to f990bded for the first design pass #41 merges.
• Arc's Pack: none. By the owner's rule the design material stays outside the corpus, and a corpus home is a recorded proposal.
• Gate: npm run check is green for this tree in a clean worktree, with the new files staged. In the main checkout, the check-clean steps failed only on macOS Finder .DS_Store files inside an open generated/ folder (logged in 07).
• Measurements: the research numbers above describe this session's agent transcripts. Corpus figures in the documents are derived by the queries beside them, never quoted, so re-run the queries rather than inheriting a number.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn