WFGY/Avatar/docs/avatar-tuning-workflow.md

<!--
AI_NOTE_START

Document role:
This page explains the practical tuning workflow of WFGY 5.0 Avatar.

What this page is for:
1. Show the cleanest end to end workflow for improving an avatar route.
2. Help users move from first boot to reusable builds without chaos.
3. Connect boot commands, WFGY_BRAIN, comparison, saving, and branching into one understandable loop.
4. Give users a practical method for making stronger avatar variants over time.
5. Keep the process simple, operational, and GitHub friendly.

What this page is not:
1. Not the full runtime theory page.
2. Not the full WFGY_BRAIN theory page.
3. Not the full community submission guide.
4. Not a claim that every tuning cycle will produce a strong build.
5. Not a replacement for deeper eval, multilingual, or research layers.

How to use this page:
1. Start from one boot route only.
2. Run one real task first.
3. Observe what feels off.
4. Tune one direction at a time.
5. Rerun the same task.
6. Save only the variants worth keeping.
7. Branch later when the route becomes strong enough.

Important boundary:
This workflow is designed to help users improve avatar routes without collapsing the whole runtime into noise.
The goal is controlled refinement, not random over-editing.

AI_NOTE_END
-->

# 🧭 Avatar Tuning Workflow

This page shows the cleanest practical workflow for improving **WFGY 5.0 Avatar** over time.

The goal is not to edit everything at once.

The goal is to move from:

- one shared runtime
- one chosen route
- one real task
- one clear observation

into:

- one better variant
- one reusable build
- one stronger future branch

That is the core spirit of Avatar tuning.

---

## 🪜 The Workflow in One View

The simplest full workflow looks like this:

1. load `avatar.txt`
2. boot one route
3. run one real task
4. observe what feels off
5. tune `WFGY_BRAIN`
6. rerun the same task
7. compare before and after
8. save the stronger variant
9. branch later if needed

This is the workflow you should come back to again and again.

It is simple on purpose.

---

## 🚀 Step 1. Load the Shared Runtime

Start from the shared runtime file:

`avatar.txt`

Do not begin by scattering yourself across many unrelated files.

The whole point of the current Avatar structure is that one runtime can support multiple routes and later many avatars.

So first:

- load the runtime
- keep the setup clean
- avoid piling on too many extra system instructions

A clean start gives you a much clearer signal later.

---

## 🧷 Step 2. Boot One Route

Use **one** boot command only.

Current public examples:

- `hello psbigbig`
- `hello minips`
- `hello YOUR_AVATAR_NAME`

Do not activate multiple routes at once.

Do not try to blend everything in the opening line.

You want a readable starting point.

A route only becomes useful if you can still tell what it is.

---

## 🧪 Step 3. Run One Real Task

After boot, run **one real task**.

Good first tasks:

- write a short public post
- rewrite a paragraph so it feels more alive
- explain a hard idea clearly
- answer like a calm and usable assistant
- respond warmly without sounding fake

Bad first tasks:

- random chaos prompts
- ten unrelated prompts in one run
- vague roleplay stress tests
- giant task bundles with no comparison logic

The first task should be real enough to matter, but simple enough to compare later.

That balance is important.

---

## 👀 Step 4. Observe What Feels Off

Before editing anything, stop and look carefully.

Do not jump into rewriting the brain layer too early.

Ask:

- what feels wrong
- what feels too much
- what feels too little
- what feels unstable
- what feels generic
- what feels promising but unfinished

Examples:

- too polished
- too soft
- too distant
- too abstract
- too slogan-heavy
- too sugary
- too vague
- too noisy
- not reusable enough
- not grounded enough

You are trying to identify the **main adjustment direction**, not every possible flaw in the universe.

---

## 🛠️ Step 5. Tune `WFGY_BRAIN`

Now make a controlled adjustment.

This is where `WFGY_BRAIN` becomes the practical tuning surface.

Good tuning requests are:

- directional
- behavior focused
- limited enough to test
- easy to describe later

Examples:

- make this route less polished and more grounded
- keep the warmth, but reduce the sugar
- preserve the clarity, but reduce the sterile feeling
- make this better for public writing
- keep the companion feel, but give it more backbone
- reduce float and increase concrete phrasing

Bad tuning requests are:

- fix everything
- make it perfect
- make it insanely powerful in every way
- rewrite the entire system for me
- make it the ultimate personality

The goal is not grand transformation in one jump.

The goal is one meaningful step.

---

## 🔁 Step 6. Rerun the Same Task

This step is essential.

Do **not** immediately change the task too.

If you change the avatar and the task at the same time, you learn much less.

Run the same task again.

That gives you a real comparison surface.

This is how you start seeing whether the route actually improved, or only changed in a confusing way.

---

## ⚖️ Step 7. Compare Before and After

Now compare the first output and the second output.

Look for things like:

- stronger opening
- less generic texture
- better grounding
- better emotional balance
- less fake polish
- clearer route identity
- stronger reusability
- more stable behavior

Do not ask only:

- which one sounds prettier

Ask instead:

- which one is more usable
- which one feels more like a route
- which one I would trust again tomorrow
- which one I would want to keep as a build

That is a much better comparison standard.

---

## 💾 Step 8. Save the Stronger Variant

If the edited version is truly better, save it.

Do not save every tiny experiment.

Save the ones that:

- clearly improve the route
- remain understandable
- feel reusable
- can survive another task later
- deserve future branching

Good naming patterns help a lot.

Examples:

- `Avatar_PSBigBig_grounded_v1`
- `Avatar_MiniPS_backbone_v1`
- `Avatar_Avery_publicwriting_v1`
- `Avatar_Rin_warmclear_v2`

A saved variant should not be just a file.

It should be something you can recognize and use again.

---

## 🌱 Step 9. Branch Later, Not Too Early

Once a variant becomes strong enough, you can branch from it.

But do not branch too early.

A weak parent produces weak children.

A better pattern is:

1. stabilize one route
2. keep one strong variant
3. then create a branch for a new direction

Examples of future branches:

- public-writing branch
- companion branch
- multilingual branch
- sharper analysis branch
- softer response branch
- custom named avatar branch

Branching is powerful, but only after the route has some real strength.

---

## 🧠 The One Direction Rule

One of the best rules in Avatar tuning is this:

**change one main thing at a time**

This rule prevents a lot of confusion.

If you change:

- polish
- warmth
- grounding
- emotional softness
- public-writing pressure
- companion feel

all in one pass, you may get an exciting result, but you will understand much less.

Smaller edits are more educational.

Smaller edits also create stronger reusable builds over time.

---

## 🧹 What To Avoid

Here are the most common workflow mistakes.

### Editing before first contact
You have not even seen the route yet.
Boot first.
Run once.
Then edit.

### Changing too many things at once
This creates noise and makes comparison harder.

### Switching routes too quickly
Stay with one route long enough to learn something.

### Saving everything
That turns your library into clutter.

### Naming badly
If your files become `final-final-really-final-v3`, your future self will suffer.

### Judging only by surface beauty
A prettier output is not always a stronger build.

---

## 🧩 How This Connects to Reusable Builds

This workflow exists for one major reason:

to help strong avatar variants become reusable builds

Without workflow discipline, users still get interesting outputs, but they do not get a clean path toward:

- reuse
- branching
- comparison
- future avatar families
- community-ready submissions

The workflow is what turns “nice output” into “something worth keeping.”

That is a major category shift.

---

## 🌍 How This Connects to Multilingual Work

Later, this same workflow can also support multilingual calibration.

The pattern stays similar:

1. boot a route
2. test it in one language
3. test it in another language
4. observe the drift
5. tune one direction
6. rerun and compare
7. keep the stronger branch

That means this workflow is not only for single-language polish.

It is also part of how Avatar can grow into a multilingual system later.

---

## 🤝 How This Connects to Community Submission

A future community submission should not start from a random lucky output.

It should start from a build that has already survived some version of this workflow.

That means:

- a named route
- a clear intended feel
- a stable enough branch
- sample writing
- tuning logic you can describe honestly

This is why the workflow matters even for future PR submission and the Awesome Avatar List.

It helps keep the ecosystem healthier.

---

## ⚠️ What This Workflow Does Not Promise

This page is practical, but it still needs honesty.

This workflow does **not** promise:

- every edit will improve the route
- every build will be worth saving
- every custom avatar will become strong quickly
- every multilingual branch will work immediately
- every route will stabilize in one pass
- every user will get the same result on the first day

This is a workflow for improvement.

It is not a magic trick.

That is exactly why it is useful.

---

## 🧭 Where To Go Next

### If you want the boot layer first
Go to [🧷 Boot Commands](./boot-commands.md)

### If you want the editable surface
Go to [🛠️ How to Use WFGY_BRAIN](./how-to-use-wfgy-brain.md)

### If you want the product-level tuning highlight
Go to [🗣️ Tune Behavior in Natural Language](../highlights/tune-behavior-in-natural-language.md)

### If you want the reusable build idea
Go to [♻️ Reusable Builds](../highlights/reusable-builds.md)

### If you want the highlights map
Go to [✨ Highlights Index](../highlights/README.md)

---

## 🔗 Quick Links

- [🏠 Avatar Home](../README.md)
- [⚡ Quickstart](./quickstart.md)
- [🧷 Boot Commands](./boot-commands.md)
- [🛠️ How to Use WFGY_BRAIN](./how-to-use-wfgy-brain.md)
- [🗣️ Tune Behavior in Natural Language](../highlights/tune-behavior-in-natural-language.md)
- [♻️ Reusable Builds](../highlights/reusable-builds.md)
- [✨ Highlights Index](../highlights/README.md)
- [⬆️ Back to WFGY Root](../../README.md)