diff --git a/docs/specification/new-spec/README.md b/docs/specification/new-spec/README.md
index 8a07d9221..179048ddd 100644
--- a/docs/specification/new-spec/README.md
+++ b/docs/specification/new-spec/README.md
@@ -1,14 +1,24 @@
 # Tendermint Specification
 
 This is a markdown specification of the Tendermint blockchain.
-
 It defines the base data structures used in the blockchain and how they are validated.
 
-It contains the following components:
+XXX: this spec is a work in progress and not yet complete - see github
+[isses](https://github.com/tendermint/tendermint/issues) and
+[pull requests](https://github.com/tendermint/tendermint/pulls)
+for more details.
+
+If you find discrepancies between the spec and the code that
+do not have an associated issue or pull request on github,
+please submit them to our [bug bounty](https://tendermint.com/security)!
 
+## Contents
+
+- [Overview](#overview)
 - [Encoding and Digests](encoding.md)
 - [Blockchain](blockchain.md)
 - [State](state.md)
+- [Consensus](consensus.md)
 - [P2P](p2p/node.md)
 
 ## Overview
@@ -56,3 +66,4 @@ We call this the `State`. Block verification also requires access to the previou
 - Light Client
 - P2P
 - Reactor protocols (consensus, mempool, blockchain, pex)
+
diff --git a/docs/specification/new-spec/encoding.md b/docs/specification/new-spec/encoding.md
index 02456d84f..f401dde7c 100644
--- a/docs/specification/new-spec/encoding.md
+++ b/docs/specification/new-spec/encoding.md
@@ -6,6 +6,9 @@ Tendermint aims to encode data structures in a manner similar to how the corresp
 Variable length items are length-prefixed.
 While the encoding was inspired by Go, it is easily implemented in other languages as well given its intuitive design.
 
+XXX: This is changing to use real varints and 4-byte-prefixes.
+See https://github.com/tendermint/go-wire/tree/sdk2.
+
 ### Fixed Length Integers
 
 Fixed length integers are encoded in Big-Endian using the specified number of bytes.
@@ -94,13 +97,13 @@ encode([]string{"abc", "efg"})  == [0x01, 0x02, 0x01, 0x03, 0x61, 0x62, 0x63, 0x
 ```
 
 ### BitArray
-BitArray is encoded as an `int` of the number of bits, and with an array of `uint64` to encode 
+BitArray is encoded as an `int` of the number of bits, and with an array of `uint64` to encode
 value of each array element.
 
 ```
 type BitArray struct {
-    Bits  int      
-    Elems []uint64 
+    Bits  int
+    Elems []uint64
 }
 ```
 
@@ -192,8 +195,8 @@ MakeParts(object, partSize)
 
 ```
 type Part struct {
-	Index int                
-	Bytes byte[]         
-	Proof byte[]             
+	Index int
+	Bytes byte[]
+	Proof byte[]
 }
 ```