User Stories

This section details how you add a feature to Mortimer. Basically you write a thorough user story. Keep it short and sweet and with a clear scope and confined to a particular domain. Later you can refine and improve in a series of refactorings.

Building a feature

Building a feature in Mortimer is a concerted effort between you and your AI. There is a scaffold to base your work off but you are by no means restricted by this protocol - it is there as an offer/opportunity.

You might find similarities with The Deming Cycle - and it is no coincidence!

Working in this structured way will even get you closer to earning yourself an ISO9000 Certificate should you so be inclined! The ISO9000 Quality System Doctrine posits: plan what you will do, do it, prove you did it - rinse and repeat. That, obviously, is a gross exaggeration but I guess you get the sentiment?

Protocol

The protocol is really nothing more than a series of tasks.

1. [P] Add a text file with a descriptive name

• File name will also (by default) become a branch in the repo,
• Use no spaces - use '- _' - eg. user-story not user stories,
• Files contains simple text using Markdown for text formatting,
• Files can (should) only build on existing artifacts - just like building an actual house (you cannot lay the roof before erecting the walls),
• Place the story in /docs/manuals/user_stories/stories

You can edit the files with your preferred editor - it's just simple text - or use special apps like JotBird.

2. [D] Realizing the feature

Ask 'chet' to look for a user story

'chet' will:

• find any new user stories and if there are more than one, ask of you which one to work on
• do a traditional PDCA on the feature. You can do it yourself no problem but involving AI at this moment is a solid choice.
• produce a /docs/plans/<name_of_your_story>.md
• await your 'go' (or provided you actually read/edited the plan) do another planning stage
• checkout a fresh branch in the repo with
  git checkout -B <name_of_your_story>
• produce the planned artifacts (routes, controllers, models, views, jobs, services, tests)
• test the artifacts
• provided you are satisfied, move the plan to docs/completed_plans/ and
• rewrite the user story into a user guide in /docs/manuals/docs/guides/<feature>/page.md and
• move the story greenbox/docs/src/docs/user-stories/stories/<feature.md> to greenbox/docs/src/docs/user-stories/completed-user-stories/<feature.md>
• and finally update a WORKLOG

3. [C] Test the feature

While implementing the feature, Mortimer did produce a sizeable test regiment but you can automate so much and no more, hence we urge you to do a series of tests to gauge the quality of the feature. Order any deficiencies into 3 buckets:

• bugs/errors
• misunderstandings/short-comings
• new demands/change requests

Let 'chet' do incremental improvements on the first bucket. AI models are exceptionel at this task! Let'm have a stab at bucket #2 but embrace yourself - if misunderstood once there is a pretty good chance the worthing, design, or some other angle is too particular for a LLM to pick up on!

4. [A] Evaluate and rethink/redesign

Carefully consider the last two buckets. If the misunderstandings are dominant - drop the entire branch and start over you did after all only waste a few dollars worth of tokens, and 1-2hrs tops!

Handle change requests like any new feature/user story. Take your time to explain the use case. Look in the docs/manuals/user-stories/completed-user-stories for inspiration.