Files
plan2code/skills/plan2code-0-pathfinder/references/web-console/public/starters.js
T

255 lines
14 KiB
JavaScript

// Plan2Code Web Console - roles, starter templates and Ask starter questions.
//
// The source of truth for the Role list in User Preferences, the starter
// templates on the first "What's the idea?" card of Pathfinder, Plan and Quick
// Task, the order each role sees them in, and the starter questions an empty
// Ask conversation offers. No DOM access at module scope and no imports: the
// page and `node --test` both import this file.
const role = (id, label) => Object.freeze({ id, label });
export const ROLES = Object.freeze([
role("engineer", "Engineer"),
role("pm", "Product lead / PM"),
role("architect", "Architect / tech lead"),
role("designer", "Designer (UX)"),
role("qa", "QA / test engineer"),
role("em", "Engineering manager"),
]);
export const ROLE_NOT_SET = "none";
export const ROLE_NOT_SET_LABEL = "Not set / none of these";
export const TEMPLATE_WORKFLOWS = Object.freeze(["pathfinder", "plan", "quick-task"]);
const ROLE_IDS = new Set(ROLES.map((r) => r.id));
// A known role id, or "none" for anything else (missing, unknown, not a string).
export function normalizeRole(value) {
return ROLE_IDS.has(value) ? value : ROLE_NOT_SET;
}
// The dashboard nudge shows until looks.json carries a role of any value:
// choosing Not set, or pressing Not now, ends it just as a real role does.
export function needsRoleNudge(looks) {
if (!looks || typeof looks !== "object") return true;
return !Object.hasOwn(looks, "role");
}
// The wording is approved (PLAN-DRAFT Appendix A); a change is a page change.
const template = (id, label, lines) => Object.freeze({ id, label, text: lines.join("\n") });
export const TEMPLATES = Object.freeze({
"engineering-spec": template("engineering-spec", "Engineering spec", [
"Engineering spec for: [the feature or change, in a sentence]",
"Who reads it: the engineers who will build and review it.",
"What it should pin down: the behaviour, the parts of the code it touches, the interfaces between them, and how we'll know it works.",
"What I already know: [constraints, links, earlier attempts]",
]),
"product-requirements": template("product-requirements", "Product requirements", [
"Product requirements for: [the feature, in a sentence]",
"Who it's for: [the users], and the product, design and engineering people deciding on it.",
"What it should pin down: the problem, who has it, what success looks like, and what waits for later.",
"What I already know: [customer asks, data, deadlines]",
]),
"design-decision": template("design-decision", "Design decision", [
"A design decision to work out: [the choice we're facing, in a sentence]",
"Who it's for: the engineers and architects who will live with it.",
"What it should pin down: the options, the trade-offs of each, the one we pick and why, and what it costs us later.",
"Constraints: [performance, compatibility, deadlines, team skills]",
]),
"test-strategy": template("test-strategy", "Test strategy", [
"Test strategy for: [the feature or area]",
"Who reads it: QA and the engineers writing the tests.",
'What it should pin down: what\'s risky, what gets tested at which level (unit, integration, end to end, by hand), the test data needed, and what "done" means.',
"What exists today: [current tests, known gaps]",
]),
"scoping-rollout": template("scoping-rollout", "Scoping & rollout", [
"Scoping and rollout for: [the feature or project]",
"Who reads it: the engineering manager, the product lead and the team.",
"What it should pin down: what's in the first release and what waits, the build order, risks to the timeline, and how it reaches users (flags, stages, who goes first).",
"Constraints: [dates, people, dependencies]",
]),
"brainstorm-notes": template("brainstorm-notes", "Brainstorm → curated notes", [
"Brainstorm to turn into curated notes: [the topic or rough idea]",
"Who reads the notes: [the team or people this goes to]",
"What I want out of it: the ideas worth keeping, grouped, with the open questions, and the ones we dropped and why.",
"Starting thoughts: [anything already on your mind]",
]),
"bug-investigation": template("bug-investigation", "Bug investigation", [
"Bug to investigate: [what's going wrong, in a sentence]",
"Steps to reproduce: [1. ... 2. ...]",
"Expected: [what should happen]. Actual: [what happens instead]",
"Where and since when: [environment, version, first seen]",
]),
"small-change": template("small-change", "Small change", [
"Small change: [what to change, in a sentence]",
"Where: [the file, screen or command, if you know it]",
"Done when: [how you'll tell it worked]",
]),
"copy-tweak": template("copy-tweak", "Copy / content tweak", [
"Change the wording of: [the screen, message, email or doc]",
"Current text: [paste it]",
"New text: [paste it, or describe the tone you want]",
"Who reads it: [the people who see it]",
]),
"ui-polish": template("ui-polish", "UI polish", [
"UI polish on: [the screen or component]",
"What looks or feels off: [spacing, alignment, colour, states, small screens]",
"What good looks like: [a reference, screenshot or description]",
"Leave alone: [anything that must not move]",
]),
"visual-prototype": template("visual-prototype", "Visual prototype", [
"A throwaway visual prototype of: [the screen or component]",
"What to show: [the states or flows to click through]",
"What I want to learn: [the question it should answer]",
"Where it lives: a prototypes/ folder [or its own branch], never wired into the real code.",
]),
"add-a-test": template("add-a-test", "Add a test", [
"Add a test for: [the function, behaviour or bug]",
"Cases to cover: [the normal case, the edge cases, the bug it guards against]",
"Where tests live: [the test file or folder, if you know it]",
]),
"record-decision": template("record-decision", "Record a decision", [
"Record a decision we've already made: [the decision, in a sentence]",
"Why: [the reasons, and what we turned down]",
"What it commits us to: [the consequences]",
"Save it as an ADR in: docs/adr/ [or wherever this repo keeps them]",
]),
});
const orders = (byRole) => Object.freeze(Object.fromEntries(Object.entries(byRole).map(([r, ids]) => [r, Object.freeze(ids)])));
// One full order per role per skill. No "none" row: Not set reads Engineer's.
export const TEMPLATE_ORDERS = Object.freeze({
pathfinder: orders({
engineer: ["engineering-spec", "design-decision", "test-strategy", "scoping-rollout", "product-requirements", "brainstorm-notes"],
pm: ["product-requirements", "brainstorm-notes", "scoping-rollout", "engineering-spec", "design-decision", "test-strategy"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "brainstorm-notes"],
designer: ["brainstorm-notes", "product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy"],
qa: ["test-strategy", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision", "brainstorm-notes"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "design-decision", "brainstorm-notes"],
}),
plan: orders({
engineer: ["engineering-spec", "bug-investigation", "design-decision", "test-strategy", "scoping-rollout", "product-requirements"],
pm: ["product-requirements", "scoping-rollout", "engineering-spec", "test-strategy", "design-decision", "bug-investigation"],
architect: ["design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "product-requirements", "bug-investigation"],
designer: ["product-requirements", "design-decision", "engineering-spec", "scoping-rollout", "test-strategy", "bug-investigation"],
qa: ["test-strategy", "bug-investigation", "engineering-spec", "product-requirements", "scoping-rollout", "design-decision"],
em: ["scoping-rollout", "engineering-spec", "product-requirements", "test-strategy", "bug-investigation", "design-decision"],
}),
"quick-task": orders({
engineer: ["small-change", "bug-investigation", "add-a-test", "ui-polish", "record-decision", "copy-tweak", "visual-prototype"],
pm: ["copy-tweak", "small-change", "visual-prototype", "ui-polish", "bug-investigation", "add-a-test", "record-decision"],
architect: ["record-decision", "small-change", "bug-investigation", "add-a-test", "visual-prototype", "ui-polish", "copy-tweak"],
designer: ["ui-polish", "visual-prototype", "copy-tweak", "small-change", "bug-investigation", "add-a-test", "record-decision"],
qa: ["add-a-test", "bug-investigation", "small-change", "ui-polish", "copy-tweak", "visual-prototype", "record-decision"],
em: ["small-change", "record-decision", "add-a-test", "bug-investigation", "copy-tweak", "ui-polish", "visual-prototype"],
}),
});
const roleRow = (role) => {
const r = normalizeRole(role);
return r === ROLE_NOT_SET ? "engineer" : r;
};
/**
* The idea card's template row for a skill: Blank first, then the skill's
* templates in the role's order. The first template carries `forYou` only for
* a chosen role, never for Not set. `[]` for a skill with no templates.
*/
export function templatesFor(workflow, role) {
if (!TEMPLATE_WORKFLOWS.includes(workflow)) return [];
const chosen = normalizeRole(role) !== ROLE_NOT_SET;
const ordered = TEMPLATE_ORDERS[workflow][roleRow(role)].map((id, i) => {
const { label, text } = TEMPLATES[id];
return { id, label, text, forYou: chosen && i === 0 };
});
return [{ id: "blank", label: "Blank", text: "" }, ...ordered];
}
// Swapping templates: an empty box, or one untouched since the last pick,
// swaps silently; anything the person typed asks first.
export function templateSwap({ selectedText, boxText, nextText } = {}) {
const box = typeof boxText === "string" ? boxText : "";
const selected = typeof selectedText === "string" ? selectedText : "";
return { text: typeof nextText === "string" ? nextText : "", confirm: box.trim() !== "" && box !== selected };
}
// Ask starter questions (PLAN-DRAFT Appendix B, approved). `lead` names the
// roles that see a starter first; `needsContext` starters wait for
// + Add context.
const starter = (id, text, lead, needsContext = false) =>
Object.freeze({ id, text, lead: Object.freeze(lead), needsContext });
export const STARTER_SETS = Object.freeze({
pathfinder: Object.freeze([
starter("pathfinder-files", "Which files or parts of the code does this decision touch?", ["engineer", "architect"], true),
starter("pathfinder-prior-art", "Has anything like this been done elsewhere in the repo?", ["engineer", "architect"]),
starter("pathfinder-decided", "What have we already decided, and what's still open?", ["pm", "em", "architect"]),
starter("pathfinder-plain", "What does this question mean, in plain words?", ["pm", "designer", "em"], true),
]),
plan: Object.freeze([
starter("plan-files", "Which existing files would this plan change?", ["engineer", "architect"]),
starter("plan-test", "How would we test this?", ["qa", "engineer"], true),
starter("plan-risks", "What are the biggest risks or unknowns in this plan?", ["architect", "em", "qa"]),
starter("plan-plain", "Explain this section as if I'm not an engineer.", ["pm", "designer", "em"], true),
]),
document: Object.freeze([
starter("document-touch", "Where does this phase touch existing code?", ["engineer"], true),
starter("document-guesses", "Which parts of this phase are still guesses?", ["architect", "engineer"], true),
starter("document-users", "What will users notice once every phase ships?", ["designer", "pm", "qa"]),
starter("document-summary", "Summarize the phases written so far in three bullets.", ["pm", "em"]),
]),
build: Object.freeze([
starter("build-last-task", "What changed in the last task, and why?", ["engineer", "em", "qa"]),
starter("build-finding", "Where exactly is this finding in the code?", ["engineer", "qa"], true),
starter("build-progress", "How far along are we, and what's next?", ["em", "pm"]),
starter("build-check", "What should I check by hand after this phase?", ["qa", "designer"]),
]),
"quick-task": Object.freeze([
starter("quick-task-files", "Which files will this touch?", ["engineer"]),
starter("quick-task-pattern", "Is there a similar pattern in the code I should follow?", ["engineer", "architect"]),
starter("quick-task-size", "Is this bigger than a quick task?", ["em", "architect"]),
starter("quick-task-try", "How do I try this out once it's done?", ["qa", "designer", "pm"]),
]),
dashboard: Object.freeze([
starter("dashboard-project", "What does this project do, in a paragraph?", ["pm", "designer", "em"]),
starter("dashboard-which-skill", "Which skill should I use for my idea?", ["pm", "designer", "em"]),
starter("dashboard-difference", "What's the difference between Pathfinder, Plan and Quick Task?", []),
starter("dashboard-spec", "Where does this spec stand?", ["pm", "em"], true),
]),
general: Object.freeze([
starter("general-step", "What is this step going to do, and what will it change?", []),
starter("general-summary", "Summarize this session so far.", ["em", "pm"]),
starter("general-left", "What's left to do after this?", ["em", "pm"]),
]),
});
// Workflows missing here (init, init-update, revise-plan, finalize, handoff,
// anything unknown) use the general set.
export const STARTER_SET_FOR = Object.freeze({
pathfinder: "pathfinder",
plan: "plan",
document: "document",
implement: "build",
"implement-review": "build",
review: "build",
"quick-task": "quick-task",
dashboard: "dashboard",
});
/**
* The starters an empty Ask conversation offers: the workflow's set, minus
* those that need context until some is attached, with the role's leads
* first and written order kept inside each group. Not set leads as Engineer.
*/
export function startersFor(workflow, role, { hasContext } = {}) {
const setId = Object.hasOwn(STARTER_SET_FOR, workflow) ? STARTER_SET_FOR[workflow] : "general";
const lead = roleRow(role);
const shown = STARTER_SETS[setId].filter((s) => hasContext || !s.needsContext);
const first = shown.filter((s) => s.lead.includes(lead));
const rest = shown.filter((s) => !s.lead.includes(lead));
return [...first, ...rest].map(({ id, text }) => ({ id, text }));
}