docs(aidd-dev): simplify implementation rules and require workflow evidence - #950

Hello
I checked the current implementation of this PR, and it already addresses the implementation-side gap: 02-execute now requires the real affected workflow, a complete successful run, observable evidence, and a blocked state when validation cannot be completed. 03-finalize also allows the required runtime to be started.
One related boundary remains unchanged: 05-review/actions/02-review-functional.md still states “Static review only, no app execution or browser.” Is this intentionally out of scope for this PR?
If so, should the review contract explicitly report when an acceptance criterion requires runtime behavior but no prior execution evidence is available, so that a statically complete diff is not presented as functionally verified?

@blafourcade ,

Qu'est-ce que tu penses de ça ?

• On limite les instructions à l'essentiel
• Plus de mermaid
• Supprime les tests c'est du gâchis de tokens, utiliser des rules
• Pourquoi avoir supprimé les numéros d'actions dans les skills ?

Evidemment on répercutera sur les autres skills si tu penses que ça fait sens aussi 🤜

@blafourcade ,

Qu'est-ce que tu penses de ça ?

• On limite les instructions à l'essentiel
• Plus de mermaid
• Supprime les tests c'est du gâchis de tokens, utiliser des rules
• Pourquoi avoir supprimé les numéros d'actions dans les skills ?

Evidemment on répercutera sur les autres skills si tu penses que ça fait sens aussi 🤜

@alexsoyes

Oui, c'est une bonne idée.

Le Mermaid est utile ici : il montre clairement le flow pour l’humain comme pour l’IA. Le gain en token est minimal vs la plus value je trouve.

Pour les numéros, autant aller au bout et les retirer aussi des noms de fichiers : prepare.md, execute.md, finalize.md. L’ordre reste porté par le flow.

Tu l’as testé sur quels types et quelles tailles de features ?

@waewoo Yes, this is intentionally out of scope for this PR. I agree that the review should explicitly report missing runtime evidence rather than present the behavior as verified. Could you create a dedicated issue for this?

@blafourcade ,
Qu'est-ce que tu penses de ça ?

• On limite les instructions à l'essentiel
• Plus de mermaid
• Supprime les tests c'est du gâchis de tokens, utiliser des rules
• Pourquoi avoir supprimé les numéros d'actions dans les skills ?

Evidemment on répercutera sur les autres skills si tu penses que ça fait sens aussi 🤜

@alexsoyes

Oui, c'est une bonne idée.

Le Mermaid est utile ici : il montre clairement le flow pour l’humain comme pour l’IA. Le gain en token est minimal vs la plus value je trouve.

Pour les numéros, autant aller au bout et les retirer aussi des noms de fichiers : prepare.md, execute.md, finalize.md. L’ordre reste porté par le flow.

Tu l’as testé sur quels types et quelles tailles de features ?

Hello @blafourcade,

On the gouvernail during the level implementation, this is way I needed this because sometimes it says "done", but it wasn't.

Should I also add a default commit behavior?

I mean, during the implementation process, by default, which phases/category should be committed?

I'll propose something.

@blafourcade as for the removal on the number, I am strongly against it, because it brings:

• clarify on the flow
• clear steps
• logical sequencing
• readibility

And I do not see any drawbacks apart from having to choose an order

Nice improvement over committing every phase/step.

I have one question about the commit unit itself. Should commit boundaries necessarily follow the AIDD plan structure (### categories / phases), or should they primarily follow logical changes?

For example, a small feature may go through several AIDD phases/categories and update multiple aidd_docs artifacts, while still representing a single coherent change from a Git perspective. In that case, preserving category boundaries can still result in several small commits that do not provide much additional review or revert value.

I see AIDD phases/categories primarily as execution boundaries for the agent, while Git commits are history/review boundaries. Those boundaries do not necessarily have to match.

Would it make sense for after feature to allow all related implementation, tests, documentation, and AIDD status updates to land in a single coherent commit when they form one logical change, while keeping multiple commits when the feature actually contains independently reviewable or revertible changes?

In other words, could the rule be closer to one commit per coherent logical change, with the plan structure guiding execution but not necessarily dictating Git history?

Very nice question, I would say:

Plan
└── Phases
    └── Tasks (« Tasks to do »)
        └── Steps

This is the original idea.

Having a commit per TASK now (not phase) allows use to pin-point where the AI made a mistake.

We want it to follow the plan, and if the plan has been properly made, commits should be logical.

But this brings that question:

Do you want your git history to have the same sequence as your plans? (I think you should, this will make debugging so much easier IMO)

cc @blafourcade @waewoo

Thanks @alexsoyes for the clarification!

I agree that one commit per validated TASK makes sense for traceability and debugging. Having commits follow the plan's TASK sequence seems like a good approach.

My initial concern was about TASK boundaries not always matching logical commit boundaries. After reviewing 01-plan and 02-implement, I see that the framework already addresses much of this through coherent, verifiable phases and commits that include all changes related to a TASK.

The only small improvement I'd suggest is making TASK decomposition guidance more explicit in 01-plan: ideally, TASKs should represent coherent, independently verifiable changes, rather than splitting implementation, tests, and documentation by default.

That would help ensure the plan naturally produces meaningful commits, as you suggested.

Otherwise, I'm aligned with the proposed approach. Thanks!