magnus919_agent-skills/nous-branding/references/pitfalls.md

Nous Branding — Pitfalls & Known Failure Modes

This document catalogs known failure modes, gotchas, and mitigations accumulated across multiple sessions of generating Nous-branded images. Use it as a troubleshooting reference when output doesn't match expectations.

---

1. Mascot Generation Failures

1.1 Sad / Melancholic Expression

Symptom: The Nous Girl looks sad, crying, or melancholic.

Cause: Image models default to a melancholic expression for manga-style characters when the prompt doesn't specify otherwise.

Fix: Always include: "Neutral calm attentive expression — not sad, not crying" in the character description. This must be explicit negation — "calm" alone is insufficient.

1.2 Dark / Black Headphones

Symptom: The mascot appears with black or dark-colored headphones matching the scene's palette.

Cause: The model matches the headphones to the scene's dominant colors instead of the brand's canonical white headphones.

Fix: Always state both the color AND the headphone structure: "White over-ear headphones — the cushioned white band arches across the crown."

1.3 Teardrop / Facial Markings

Symptom: A teardrop appears under the eye, or the face has tattoos, scars, or cyberpunk markings.

Cause: The model free-associates "manga" or "cyberpunk" with facial markings.

Fix: Include explicit exclusions: "No tattoos, no scars, no markings, clean clear skin. No teardrop."

1.4 Wrong Ethnicity

Symptom: The Nous Girl appears Asian instead of French/Caucasian.

Cause: Image models default to Asian features when the prompt specifies "anime" or "manga" style.

Fix: Explicitly state: "French Caucasian, fair skin, light-colored eyes (blue or grey), delicate European features, about 13 years old — NOT Asian."

1.5 Wrong Clothing / Costume

Symptom: The character is dressed in a hoodie, dark cyberpunk outfit, or elaborate costume instead of the brand's white collared shirt.

Cause: The model matches the character's clothing to the scene's aesthetic rather than the brand specification.

Fix: Always state "white collared shirt" and add "not a hoodie, not a dark top" for complex scenes.

1.6 Generic Anime Instead of Retro Manga

Symptom: Output looks like modern glossy anime rather than 1970s-80s cel-shaded manga.

Fix: Use the exact phrase "1970s-80s cel-shaded manga style, high-contrast black ink on white paper".

---

2. Image Editing / Reference Workflow Pitfalls

2.1 Text Disappears from Edited Images

Symptom: When editing an image that contains text (meme captions, labels, headlines), the model corrupts or drops the text.

Fix: Regenerate with "Keep all text exactly as shown. Do not change or remove any text." Or add text as a post-processing step. This is a known limitation of the /v1/images/edits endpoint.

2.2 Square Input Requirement

Symptom: The edits endpoint rejects non-square input images.

Fix: The generate-with-ref.py script handles this by center-cropping to 1024x1024. Use --pad to pad with average edge color instead of cropping.

2.3 Reference Is Not a Guarantee

Symptom: Uploading the official Nous Girl badge as a reference doesn't guarantee the output matches the canonical design.

Cause: /v1/images/edits does not extract style embeddings like IPAdapter or ControlNet. The reference provides pixel-level context but style transfer is not guaranteed.

Fix: Always restate all key identifiers in the text prompt (white headphones, black hair, white collared shirt, neutral expression) AND all exclusions (no teardrop, no markings). Prefer the sketch sheet (nous-girl-sketch-sheet.png) over a single-pose badge for better character understanding.

2.4 Multi-Pass Editing Complexity

Symptom: Each editing pass degrades image quality or loses fidelity.

Fix: Limit to 3-4 passes maximum. Each pass handles ONE transformation. The working sequence: character swap → style conversion → demographic correction. More passes introduce cumulative artifacts.

2.5 Aspect Ratio Confusion

Symptom: Output is cropped or distorted when using non-square source images.

Fix: The edits endpoint outputs landscape (1536x1024), portrait (1024x1536), or square (1024x1024). Set the desired output size explicitly via the size parameter in generate-with-ref.py or via --aspect flag.

---

3. Safety / Moderation Blocks

3.1 OpenAI Moderation Rejects Horror Content

Symptom: The safety system blocks prompts containing ominous language, body horror descriptors, or threat-adjacent vocabulary.

Fix: Strip all emotional/response language from the prompt. Describe only neutral visual phenomena. Instead of "horrifying spiral consuming the town," use "spiral shapes in the clouds and on buildings." The concept survives through visual contrast alone — no need to label it as horror.

Known blockers: terrifying, disturbing, grotesque, contorted, twisted (when applied to figures), Uzumaki, body horror.

3.2 Threatening Character Descriptions

Symptom: /v1/images/edits blocks prompts with "henchmen," "weapons," "crime scene," or threatening-character groups.

Fix: Rephrase as neutral physical descriptions: "a group of men in dark suits" not "henchmen." Remove weapon references. Describe the scene's visual elements without labeling their intent.

---

4. Provider-Specific Quirks

4.1 OpenAI /v1/images/edits

Issue	Workaround
Text vanishes from edits	Include explicit preservation instructions
Square input only	Use --pad flag to preserve non-square content
Extra auto-generated text (labels, headlines)	Explicitly specify "ONLY the following text: [exact text]. No other text anywhere."
Reference doesn't guarantee fidelity	Restate all identifiers in prompt

4.2 DALL-E 3 (Text-Only)

Issue	Workaround
Can't use reference images	Must specify all details in the prompt text
Sad default expression	Explicit negation required
Wrong headphones	Must specify color and structure
Safety system blocks horror	Strip emotional language, describe visual phenomena only

4.3 ComfyUI / IPAdapter

Issue	Workaround
Reference can overpower prompt	Lower denoise to 0.6-0.7
Texture/loss of analog feel	Post-process with scripts/postprocess.py
Style transfer incomplete	Use Reference-Only ControlNet not just IPAdapter

---

5. Prompt Engineering Anti-Patterns

5.1 Not Specifying Emotional State

The single most important lesson: if the prompt says anything about the character's emotional state without specifying "not sad," the model defaults to sad. Always end character descriptions with explicit negations of the default failure modes.

5.2 Not Specifying Ethnicity

For manga-style characters, the model defaults to Asian features. Always state "French Caucasian" for the Nous Girl.

5.3 Assuming Reference Images Replace Text Description

Uploading a reference image does NOT replace the need for a detailed text prompt. The reference influences style and composition, but the model still needs to know what to generate. Always provide:

• Character identifiers (hair, headphones, shirt)
• Palette constraints (hex values if possible)
• Expression (with exclusions)
• What NOT to include (teardrop, markings, dark headphones)

---

6. Pipeline / Tooling Pitfalls

6.1 generate-with-ref.py Crashes

If the script crashes, check:

• Python dependencies: pillow installed?
• Reference path exists: ls -la assets/
• Config file readable: ~/.hermes/config.yaml
• Active image provider set in config

6.2 Post-Processing Too Aggressive

If scripts/postprocess.py --mode imprint destroys too much detail, reduce intensity or switch mode:

• --intensity 0.45 for fine linework
• --mode nous for legacy luminous targets (no xerox/registration/scuffs)
• --mode standard for light touch only

6.3 Reference Images Are Placeholders

The assets in assets/ are full-resolution reference images. If the skill was installed via cp -r and the assets directory is empty, sync from the repo:

cp -r /path/to/agent-skills/nous-branding/assets/ ~/.hermes/skills/creative/nous-branding/assets/

---

Quick Reference: Fixes for Common Problems

Problem	Fix
Sad expression	Add "not sad, not crying" to prompt
Black headphones	Specify "white over-ear headphones" + "cushioned white band arches across crown"
Teardrop/markings	Add "no tattoos, no scars, no markings, no teardrop"
Wrong ethnicity	Add "French Caucasian, NOT Asian"
Wrong clothing	Add "white collared shirt, not a hoodie"
Glossy anime instead of manga	Use "1970s-80s cel-shaded manga style, high-contrast black ink on white paper"
Text disappears in edits	Add "Keep all text exactly as shown" or add text post-process
Image too clean	Run python3 scripts/postprocess.py input.png output.png --mode imprint --intensity 0.7
Reference not matching	Use sketch sheet, restate all identifiers in prompt