mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 04:45:33 -08:00
255 lines
14 KiB
JavaScript
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 }));
|
|
}
|