Skip to content

AI foundations

Every NepWalk warrior starts here. Six short topics on how we work: an AI coding tool in a terminal, our skills, our records and our way of finishing work. For each topic: read it, discuss it with your AI tool, then explain it back in your own words (see learning). Trying it in real work is optional.

To read these pages in your browser, open the .md file with a Markdown viewer extension (see getting started), or read them on the docs site. Easiest of all: ask your AI tool "teach me Your AI workspace".

1. Your AI workspace

Open nepwalk-docs in your preferred workspace: a terminal, VS Code or Antigravity. Use an AI tool that can read the repository instructions. Practise using the terminal for inspecting changes and running checks; an integrated terminal is fine. If the tool does not discover skills, ask it to read AGENTS.md and the matching skill file explicitly.

  • Say what you want in plain words. "What should I do today?", "start my task", "report this bug", "teach me", "done for today". Shortcuts such as /today are optional.
  • Paste screenshots. Paste or drag an image into the chat and say what is wrong. The AI reads it, writes the ticket and attaches the screenshot.
  • Skills do the routine. .agents/skills/ holds the team's skills: today, work, quality, learning, ticket, closure and planning. If your tool does not pick one up by itself, say: "Read AGENTS.md and follow the team-today skill."
  • The AI records everything with node tools/team.mjs: tasks, tickets, learning and your hours. You do not edit the record files yourself.
  • Every answer ends with the next step. If it does not, ask "what next?".
  • The dashboard (node tools/team.mjs open) shows the same records. It is the fallback, not the main tool.

Explain it back:

  • Where do you open your AI tool, and why there?
  • How do you report a bug you can see on your screen?
  • What do you do when the AI does not seem to know the team skills?

2. Give AI a clear task and context

An AI tool only knows what it can read and what you tell it. Vague requests get confident guesses; clear ones get useful work.

A clear request has:

  • The goal: what should be true when it is done, for whom.
  • The scope: what to change, and what to leave alone.
  • The context: the feature card, the approved prototype, the decision, the repository's own instructions (AGENTS.md, CLAUDE.md).
  • The definition of done: the acceptance checks.
  • The evidence you expect: which checks to run and what to show you.

Weak: "Fix the footer."

Clear: "Task tidy-footer-links: remove dead links from the footer in nepwalk-fe. Do not change the footer layout. Done means every link opens a real page on phone and desktop. Run the lint and unit tests, then tell me how to check it by hand."

When something is unclear, a good AI asks instead of guessing, and so should you. Changing scope is the founder's call: report it as a ticket rather than quietly doing more.

Explain it back:

  • Why does the AI need the acceptance checks?
  • What should happen when the task brief and the feature card disagree?
  • What is one thing you should never paste into an AI tool?

3. Finish one task with AI

One task at a time, carried all the way to done. Half-finished work in many places is hard to test, review and trust.

The stages, and what each one proves:

  1. Start: the task is yours and its design is approved.
  2. Build: the change exists, inside the agreed scope.
  3. Automated checks: the code compiles and the tests pass. The AI runs them and records the real output.
  4. "It's testing time": you use it on a real phone or browser and tell the AI what you saw. Only a person can record this.
  5. Review: someone else checks the work against the acceptance checks.
  6. Acceptance: the founder accepts it. Now it is done, and the XP arrives.

While a task waits for review, you learn or report bugs; you do not start a second task. When your assigned work is done, you may pick from the backlog. If you are stuck, report the blocker early: what blocks you, what you tried, who decides.

Explain it back:

  • Why does a passing build not mean a feature works?
  • Who may record a manual test, and why?
  • What can you do while your task waits for review?

4. Check AI work and report bugs in the terminal

AI tools are helpful and sometimes wrong in a very confident voice. A warrior checks. Tell claims from evidence:

  • Claim: "All tests pass." Evidence: the command and its output, for example npm test: 42 passed.
  • Claim: "The page works on mobile." Evidence: "Pixel 7, Chrome, revision abc123: I opened the trip page and the footer stayed below the last card."

Check it yourself in the terminal:

git status           # which files changed
git diff             # exactly what changed
npm test             # run the checks yourself (in nepwalk-fe or nepwalk-be)
node tools/team.mjs brief <task-id>   # what was recorded for the task

If the AI claims a check passed without evidence, treat the result as unverified. Ask for the actual command and result; rerun it when needed.

Report a bug by talking to your AI tool:

  1. Take a screenshot and crop out names, phone numbers, emails and prices.
  2. Paste it into the chat (or drag the file in) and say what is wrong: the page, what you did, what you expected and what happened, on which device.
  3. The AI writes the ticket and attaches the screenshot. It takes the image from your clipboard or the file path. If neither works, it asks you to save the file.
  4. The founder triages it. Reporting is not permission to fix it.

Explain it back:

  • What is the difference between a claim and evidence? Give an example.
  • Which commands show you what the AI really changed?
  • What makes a bug report useful to someone else?

5. Your records and your branch

Your tasks, tickets, learning and hours are small files in docs/team/records/, one file per record. The AI writes them for you.

  • You keep one docs branch: team/<your id>, for example team/umang.
  • Each morning the AI brings in what was merged: inspect local work and integrate origin/main safely. Do not overwrite a dirty working tree or discard another person's records.
  • When you say "done for today", the AI logs your hours, writes the handoff, commits your records on your branch and opens or updates your pull request.
  • The founder merges docs, frontend and backend pull requests one by one. Your records reach the whole team with that merge. Separate record files reduce conflicts. Two people changing the same record can still conflict; inspect both versions and preserve the real history.
  • Everyone on the team can see the records. Keep company money, customers and passwords out of them.

Explain it back:

  • Where do your records live, and who writes them?
  • How do your records reach the rest of the team?
  • What happens when you say "done for today"?

6. Learn through explanation

Reading an explanation feels like understanding. Explaining it yourself shows whether you really understand it.

The learning loop:

  1. Learn the topic with AI, in small steps, with examples.
  2. Explain it back in your own words, without looking.
  3. Answer the AI's follow-up questions. They check understanding, not memory.
  4. Where an answer was weak, that is a gap. Close it, then explain again.
  5. Save a short summary in your own words.

Using it in real work later is a bonus, never a requirement. Your summaries are visible to the team, so keep them honest and short, and keep private company information out of them.

Explain it back:

  • Why is explaining better than re-reading?
  • What counts as a gap, and what do you do with one?
  • What makes a good one-sentence summary?

Continue your training

After these foundations, open AI practice. Everyone learns AI fieldcraft; engineers and managers then follow role-specific topics. Your Academy view keeps the next topic visible and records understanding separately for each person.