uhhm/portal
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 89 Wiki Activity

portal-trainer: the loop around portal's needs verifier

Browse Source 
The trainer procedure as an agent skill, the engine contract, two
sector specs (software-studio: UHHM's own, green; construction: a
target with no pages yet), and the first wording run against uhhm.no.
The verifier itself is portal's question_lint (uhhm/portal 188f9bf).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L4jrCgLiKKHAEFuZUJjckH
This commit is contained in:
Bendik Aagaard Lynghaug
2026-09-21 16:31:37 +02:00
co-authored by Claude Fable 5.1
commit 7caaa27ba7
7 changed files with 568 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
sectors/construction/needs.yaml
+158
View File
@@ -0,0 +1,158 @@
# A building contractor's needs, as a portal needs spec: a small to
# mid-sized firm doing surveys, design and rehabilitation, run by a few
# project managers with its own crew and a ring of subcontractors.
#
# This file is a target, not a description: there are no pages behind
# it yet, so `question_lint` fails every need. The trainer's job is to
# write the pages, aggregates.yaml and desks that turn it green, then
# word them until the personas route right.
#
# Groups (Kanidm): project_managers, hse, crew, subcontractors.
# Everyone else arrives anonymous.
#
# What the sector demands of the flows, and why the budgets are what
# they are:
# - Winning work is a pipeline, not an inbox: a lead is surveyed, then
# quoted, then won or lost. "answered" is not an outcome.
# - A subcontractor must be vetted before they set foot on site
# (company registration, trade approval, insurance, tax standing,
# site ID cards for their people). Documents go missing; the state
# machine has to say so and let them come back.
# - Deviation and near-miss reporting only works when it costs the
# reporter seconds. Three required fields, one submission, from a
# phone, and the safety officer owns closing it.
# - People move between firms constantly; onboarding a worker is the
# same shape as onboarding a subcontractor, one size smaller.
needs:
- id: win-survey-work
who: a building owner or housing board with a problem in their building
wants: someone qualified to look at it and say what it takes
lands_in: leads
handled_by: project_managers
done_when: [won, lost]
max_steps: 2
max_fields: 5
- id: win-design-work
who: an owner who knows what they want built or changed
wants: drawings, a permit application, and a price
lands_in: leads
handled_by: project_managers
done_when: [won, lost]
max_steps: 2
max_fields: 6
- id: vet-subcontractor
who: a trade firm that wants to work for us
wants: to be approved once, and then be asked
lands_in: subcontractors
handled_by: project_managers
done_when: [approved, rejected]
max_steps: 2
max_fields: 7
- id: request-bids
who: a project manager with a job to staff
wants: approved subcontractors to see it and answer
enters: /jobs/post
enters_as: project_managers
lands_in: job_requests
handled_by: project_managers
done_when: [awarded, withdrawn]
max_steps: 1
max_fields: 5
- id: answer-bid
who: an approved subcontractor
wants: to say yes to a job, with a price and a start date
enters: /jobs
enters_as: subcontractors
lands_in: bids
handled_by: project_managers
done_when: [accepted, declined]
max_steps: 2
max_fields: 3
- id: hire-crew
who: a tradesperson looking for work
wants: to be considered, without writing a letter
lands_in: applicants
handled_by: project_managers
done_when: [hired, declined]
max_steps: 2
max_fields: 4
- id: report-deviation
who: anyone on site - crew or a subcontractor's people
wants: to report a hazard, a near miss or a defect before they forget
enters: /site
enters_as: crew
lands_in: deviations
handled_by: hse
done_when: [closed]
max_steps: 1
max_fields: 3
personas:
- id: housing-board-damp
need: win-survey-work
text: >
I chair the board of a housing cooperative from the seventies.
Two ground-floor flats have damp in the walls and we don't know
if it's drainage or the facade. We need someone to tell us.
- id: buyer-before-purchase
need: win-survey-work
text: >
We are about to buy an old timber house. Before we sign we want
a professional to go through it and tell us what is wrong with it.
- id: attic-conversion
need: win-design-work
text: >
We want to turn our attic into two bedrooms and a bathroom. We
need drawings and someone who handles the application to the
municipality.
- id: shop-to-flat
need: win-design-work
text: >
I own a former shop on the ground floor and want to make it a
flat. I have no idea what is allowed. Can you sort that out and
give me a price?
- id: electrician-firm
need: vet-subcontractor
text: >
We are a four-person electrical firm, fully certified. We would
like to get on your list so you call us when you need
electricians.
- id: scaffolder
need: vet-subcontractor
text: >
I run a scaffolding company. How do I get to do jobs for you?
- id: carpenter-jobseeker
need: hire-crew
text: >
I'm a certified carpenter with eight years on rehabilitation
jobs. Are you hiring?
- id: apprentice
need: hire-crew
text: >
I finish vocational school this spring and need an
apprenticeship as a bricklayer.
- id: loose-railing
need: report-deviation
text: >
The railing on the third level of the scaffold on the north
side is loose. Nobody got hurt but someone will.
- id: wrong-membrane
need: report-deviation
text: >
The bathroom membrane delivered today is not the one in the
specification. We stopped work on it.
sectors/software-studio/needs.yaml
+127
View File
@@ -0,0 +1,127 @@
# What UHHM, as a business, needs this site to do - stated apart from
# how the pages word it. `question_lint` checks every need against the
# pages and aggregates.yaml (portal `src/needs.rs`): a path of
# submissions gets the visitor's answer into `lands_in` within the
# effort budget, `handled_by` has a desk over that bucket, and every
# `done_when` state is reachable through the moves the desk offers.
#
# The personas are visitors in their own words - never the site's.
# `question_lint --needs-tasks` turns each page on their path into a
# typed choice for an answering engine; `--needs-score` grades its
# picks. A misroute means the page said one thing and they heard
# another. The runtime never reads this file.
needs:
- id: commission
who: someone with a problem software could solve, and a budget
wants: UHHM to take the work on
via: Good software begins with a clear argument
lands_in: projects
handled_by: owners
done_when: [accepted, declined]
max_steps: 1
# name, email, the build, the organization - the page argues for
# each of the four; a fifth would need the same argument.
max_fields: 4
- id: follow
who: someone curious who isn't ready to get involved
wants: to hear when something ships
via: Attention is earned
lands_in: subscribers
handled_by: owners
# Being on the list is the finished state; leaving is theirs to do.
done_when: [open, unsubscribed]
max_steps: 1
max_fields: 2
- id: collaborate
who: a developer, designer or researcher
wants: to work with UHHM
via: Work happens through dialogue, not tickets
lands_in: applicants
handled_by: owners
done_when: [active, declined]
max_steps: 1
max_fields: 3
- id: improve-site
who: anyone using this site
wants: the site itself to change
enters: /develop/proposal
# Announced, not open: the automation that turns a proposal into a
# pull request is still being built, so the alternative is disabled.
planned: true
lands_in: development_proposals
handled_by: owners
done_when: [approved, rejected]
max_steps: 1
max_fields: 3
- id: track-prospect
who: an owner who met an organization worth following up
wants: the relationship written down and walked to an outcome
enters: /review
enters_as: owners
via: Record a prospect
lands_in: organizations
handled_by: owners
done_when: [client, past_client]
max_steps: 1
max_fields: 2
personas:
- id: architecture-firm
need: commission
text: >
We run a small architecture firm and our project files are
scattered across three cloud drives. We want to pay someone to
set up proper storage and backups we control ourselves.
- id: climbing-gym-founder
need: commission
text: >
I have an idea for a booking app for climbing gyms and I'm
looking for a team that can build the first version with me.
- id: municipality-buyer
need: commission
text: >
Our municipality needs an internal tool for tracking building
permits. We are looking for a vendor who can scope it and
deliver it.
- id: exhibition-visitor
need: follow
text: >
I saw your drawing network at an exhibition and liked it. I don't
want to get involved, I'd just like to know when there is news.
- id: tech-journalist
need: follow
text: >
I write about Nordic technology. Keep me posted on what you
release so I can cover it.
- id: rust-developer
need: collaborate
text: >
I'm a Rust developer between jobs and I like that you build in
the open. I would love to contribute, and maybe join you.
- id: interaction-designer
need: collaborate
text: >
I'm an interaction designer. I want to work with you on the
drawing interface.
- id: student-intern
need: collaborate
text: >
I'm a computer science student looking for a summer internship
doing infrastructure work.
- id: site-critic
need: improve-site
text: >
Your contact form never says how long a reply takes. You should
add that.